DEV Community: Asaduzzaman Pavel

The NixOS Tools That Actually Make a Difference

Asaduzzaman Pavel — Mon, 20 Apr 2026 06:37:55 +0000

The NixOS Tools That Actually Make a Difference

I run NixOS on three machines and I have the same set of tools on all of them. Not because I followed a guide, but because I hit the same friction points on each one and eventually fixed them the same way. This is that list.

comma — Run Software Without Installing It

comma is the one I show people first. You put a , in front of any command, and it finds the right package in nixpkgs, pulls it in temporarily, and runs it. Nothing gets installed permanently. Nothing pollutes your profile.

, cowsay "it just works"

Under the hood it wraps nix shell -c and nix-index together. It also caches results: once you pick a derivation for a command, it remembers, and once the path is evaluated by Nix, subsequent calls are nearly instant. The benchmarks in the repo show cache level 2 is about 159x faster than cache level 1. That number is real.

It requires a nix-index database to know where files live in nixpkgs. The companion project nix-index-database provides pre-generated databases on a regular schedule, so you can skip building one yourself.

nix-index — Find What Package Owns a File

nix-index builds a local database by indexing the binary caches. Then you query it with nix-locate to find which nixpkgs package contains a specific file.

$ nix-locate 'bin/hello'
hello.out    29,488 x /nix/store/bdjyhh70...-hello-2.10/bin/hello

The part most people actually use is the command-not-found integration. When you type a command that is not installed, your shell tells you the exact package to install instead of just printing an error. Coming from a traditional distro, this single feature makes NixOS feel less hostile.

Building the index takes around five minutes. Or skip it and use nix-index-database for a pre-built one.

nurl — Generate Nix Fetcher Calls from URLs

Writing a fetcher call by hand means figuring out the right fetcher, the right attributes, and then computing a hash by actually downloading the source. It is annoying every single time.

nurl takes a URL and an optional revision and prints a ready-to-use fetcher call with the hash filled in.

$ nurl https://github.com/nix-community/patsh v0.2.0
fetchFromGitHub {
  owner = "nix-community";
  repo = "patsh";
  tag = "v0.2.0";
  hash = "sha256-7HXJspebluQeejKYmVA7sy/F3dtU1gc4eAbKiPexMMA=";
}

It supports fetchFromGitHub, fetchFromGitLab, fetchFromGitea, fetchFromSourcehut, fetchCrate, fetchPypi, fetchhg, fetchsvn, and more. It avoids slow fixed-output derivations when faster alternatives exist. And it is the foundation that nix-init builds on.

nix-init — Generate Full Nix Packages from URLs

If nurl handles the fetching, nix-init handles everything else. Point it at a URL and it generates a complete package expression with hash prefetching, dependency inference, and license detection. All through interactive prompts with fuzzy tab completion.

Supported builders: stdenv.mkDerivation, buildRustPackage, buildPythonApplication, buildPythonPackage, and buildGoModule. For Rust projects it infers the cargo hash automatically. For Python it picks up dependencies from PyPI metadata.

The docs are honest about this: the output will probably need tweaks, and you should verify the license and description yourself. But it does the 80% that nobody wants to do manually, which is why packaging contributions happen at all.

nh — A Better CLI for NixOS, Home Manager, and Darwin

nh reimplements nixos-rebuild, home-manager switch, and darwin-rebuild with better output and a few genuinely useful additions.

Platform	Without nh	With nh
NixOS	`nixos-rebuild switch --flake .#myHost`	`nh os switch . -H myHost`
Darwin	`darwin-rebuild switch --flake .#myHost`	`nh darwin switch . -H myHost`
Home Manager	`home-manager switch --flake .#myHost`	`nh home switch . -c myHome`

The shorter syntax is nice but not the point. When you run nh os switch, you get a build tree from nix-output-monitor, a diff of what is actually changing in your derivations, and a confirmation prompt before anything gets activated. You stop switching blind.

nh clean extends nix-collect-garbage with gcroot cleanup, profile targeting, and time-based retention like --keep-since 4d. A NixOS module in nixpkgs can wire this up as an automatic service.

statix — Lint Your Nix Code

statix checks Nix files for antipatterns and fixes the ones it can.

$ statix check tests/c.nix
[W04] Warning: Assignment instead of inherit from
   ╭─[tests/c.nix:2:3]
   │
 2 │   mtl = pkgs.haskellPackages.mtl;
   ·   ─────────── This assignment is better written with inherit

$ statix fix --dry-run tests/c.nix
-  mtl = pkgs.haskellPackages.mtl;
+  inherit (pkgs.haskellPackages) mtl;

It catches redundant pattern bindings, collapsible let...in blocks, manual inherit patterns, unnecessary boolean comparisons, unquoted URIs, and more. The full list is available via statix list. Specific lints can be disabled in a statix.toml at the project root, and it respects .gitignore by default.

Plug it into your editor and forget about it.

nix-direnv — Fast, Persistent Dev Shells

nix-direnv replaces direnv's built-in use_nix and use_flake. The built-in version re-evaluates on every shell entry, which gets slow. nix-direnv caches the result and only rebuilds when your shell.nix or flake.nix actually changes.

The part I care about more: it pins the shell derivation in your Nix gcroots. Garbage collection will not delete your build dependencies. I lost hours of cached downloads to a nix-collect-garbage run before I started using this.

Setup with Home Manager:

programs.direnv = {
  enable = true;
  nix-direnv.enable = true;
};

Add use flake or use nix to .envrc, run direnv allow, and your environment loads automatically on cd. Works with classic shell.nix and flake-based devShells.

flake-parts — The Module System for Your flake.nix

Every non-trivial flake.nix eventually becomes a mess. Packages for multiple systems, devShells, CI checks, a NixOS module. You end up with 300 lines of forEachSystem repetition and nobody wants to touch the file.

flake-parts brings the NixOS module system to flakes. You split the configuration into focused files and flake-parts assembles them. It handles the system boilerplate and makes it easier for others to pull your flake's outputs into theirs.

Migration is gradual. Wrap your existing outputs in mkFlake and move things over piece by piece:

outputs = inputs@{ flake-parts, ... }:
  flake-parts.lib.mkFlake { inherit inputs; } {
    systems = [ "x86_64-linux" "aarch64-linux" ];
    # perSystem and other modules go here
  };

Projects using it include nixd, argo-workflows, and hyperswitch. It has become a standard approach for flakes that need to stay maintainable.

hjem — Home File Management Without the Overhead

If you have ever wanted Home Manager's home.file without the rest of Home Manager, hjem is worth knowing about.

Hjem ("home" in Danish) is a NixOS module that manages files in $HOME. That is mostly it. No program modules, no environment activation scripts, no opinion about your shell. You declare files and it links them into place using smfh, an atomic file linker backed by systemd services.

hjem = {
  users.k1ng = {
    enable = true;
    files = {
      ".foo".text = "bar";
      ".config/something.json" = {
        generator = lib.generators.toJSON { };
        value = { foo = 1; bar = "hello"; };
      };
    };
  };
};

It is multi-user by design. Each key under hjem.users maps to a user in users.users, and hjem refuses to manage homes for users that do not exist.

The honest comparison to Home Manager: hjem does far less. It does not abstract away program configuration. There is no programs.git.enable equivalent. The project is explicit that application-specific modules are out of scope, though a separate project called hjem-rum is building that layer on top.

I think that constraint is actually the point. Home Manager is large, occasionally opinionated in ways you did not ask for, and has a reputation for activation scripts that sometimes conflict with NixOS's own. Hjem is small enough that you can read the entire codebase in an afternoon. If all you want is declarative dotfile management wired into your NixOS config without pulling in a second module framework, hjem is the cleaner answer. It is still young at around 330 stars, so I would not call it battle-tested, but it is actively maintained and the scope is intentionally narrow enough that "mostly feature-complete" is a realistic claim.

NixOS Options Search — Keep This Tab Open

Not something you install: search.nixos.org/options.

It searches the entire set of NixOS module options. Type, default value, which module declares it. When you cannot remember if it is services.nginx.enable or programs.nginx.enable, this is where you go. It is faster than reading source, and honestly faster than grepping nixpkgs.

It also covers Home Manager options and has a package search tab. I have it open on every machine I work on.

None of these are required. NixOS runs fine without them. But each one fixes something that is genuinely annoying without it, and after a while you stop noticing the friction because you stopped having it.

TimescaleDB Continuous Aggregates: What I Got Wrong (and How to Fix It)

Asaduzzaman Pavel — Sat, 18 Apr 2026 03:50:55 +0000

I thought continuous aggregates would solve my crypto data performance problems. They did, for about three weeks. Then the wheels came off, and I spent two months untangling the mess I'd made.

If you're using TimescaleDB as your time-series database and thinking about continuous aggregates, read this first. I wish someone had warned me.

The Setup

I was storing OHLCV candlestick data (Open, High, Low, Close, Volume) for crypto pairs in TimescaleDB, a time-series database built on PostgreSQL, with millions of rows per day and queries aggregating across hours and days. Query performance on the raw hypertable was crawling, sometimes 30 seconds for a week's worth of aggregated data.

Continuous aggregates seemed like the obvious fix. In TimescaleDB, a continuous aggregate is a PostgreSQL materialized view that refreshes itself incrementally in the background: pre-compute the aggregations, query the materialized view instead of raw data, and let TimescaleDB handle the rest. Clean, simple, automatic. It was none of those things.

The First Mistake: Wrong Time Bucket Granularity

I created an hourly aggregate because I figured "hourly should be enough for most queries." It wasn't. Users wanted 4-hour candles, 6-hour candles, sometimes 2-hour. The hourly buckets were useless for them.

Here's what I didn't understand upfront: you can't query a continuous aggregate at a finer granularity than what you defined. An hourly aggregate gives you hourly data. If you want 15-minute buckets, you're hitting the raw hypertable anyway, which defeats the whole point.

-- This works fine -- same granularity as the aggregate
SELECT time_bucket('1 hour', bucket), AVG(close) FROM candlesticks_1h GROUP BY 1;

-- This has to go to the raw table -- 15-min is finer than what we materialized
SELECT time_bucket('15 minutes', time), AVG(close) FROM candlesticks_raw GROUP BY 1;

The fix was creating multiple aggregates at different granularities. And that led straight to my next problem.

Worth noting: since TimescaleDB v2.9, you can stack continuous aggregates on top of each other. So you could create a 15-minute aggregate, then build an hourly aggregate on top of it, then a daily on top of that. I didn't know this at the time and ended up doing things the hard way.

The Refresh Policy Nightmare

With three aggregate views (15-minute, hourly, daily), the refresh policies started stepping on each other. Data would appear in one view but not another. Sometimes queries returned different results depending on which view the planner hit.

-- The configuration that caused headaches
SELECT add_continuous_aggregate_policy('candlesticks_15m',
    start_offset => INTERVAL '30 minutes',
    end_offset => INTERVAL '5 minutes',
    schedule_interval => INTERVAL '5 minutes');

SELECT add_continuous_aggregate_policy('candlesticks_1h',
    start_offset => INTERVAL '2 hours',
    end_offset => INTERVAL '30 minutes',
    schedule_interval => INTERVAL '15 minutes');

The start_offset and end_offset parameters define the continuous aggregate refresh policy window, specifically what range of data gets recomputed each time the job runs. Get these wrong and you either have stale data (offsets too large) or a gap where queries return nothing (the refresh job simply hasn't caught up yet).

I spent three days wondering why the last hour of data was missing. The answer: end_offset was 30 minutes but the refresh job ran every 15. The window had materialized data up to 30 minutes ago, and the real-time aggregation that would fill that gap was disabled in my config. Once I understood the interplay between the offsets and the schedule interval, it clicked, but the documentation doesn't make this obvious.

Chunk Explosion

This one actually killed performance. Each continuous aggregate creates its own internal materialization hypertable, which means its own set of chunks. With raw data, hourly aggregates, and daily aggregates all running, I had three independent chunk hierarchies to manage.

-- Checking disk usage per table (returns one row per chunk)
SELECT * FROM chunks_detailed_size('candlesticks_raw');      -- 847 rows returned
SELECT * FROM chunks_detailed_size('candlesticks_1h');        -- 892 rows returned
SELECT * FROM chunks_detailed_size('candlesticks_daily');    -- 412 rows returned

Note: chunks_detailed_size() returns one row per chunk with size information, so the row count above is effectively your chunk count. When I saw nearly 900 chunks on a single aggregate view, I knew something had gone sideways.

Query performance started degrading rather than improving. The database was spending more time on chunk exclusion (figuring out which chunks were relevant to a query) than actually reading data. Too many small chunks and the metadata overhead overwhelms the actual work.

The fix was TimescaleDB chunk compression: compressing older chunks with a compression policy and adjusting the chunk time interval so chunks weren't being created too frequently. This isn't in the quick-start guide, but it absolutely should be.

Query Flexibility

Here's the thing nobody talks about much: continuous aggregates are rigid by design. The GROUP BY you define at creation time is the GROUP BY you're stuck with. Adding a new grouping dimension later means dropping the materialized view and rebuilding from scratch, including re-running the backfill.

-- Original aggregate
CREATE MATERIALIZED VIEW candlesticks_1h
WITH (timescaledb.continuous) AS
SELECT
    time_bucket('1 hour', time) AS bucket,
    pair,
    AVG(close) AS close,
    MAX(high) AS high,
    MIN(low) AS low
FROM candlesticks_raw
GROUP BY bucket, pair;

A few weeks after shipping this, a stakeholder asked: "Can we group by exchange too?" The answer was either rebuild everything and backfill, or query raw data. Both defeated the purpose.

There's no ALTER MATERIALIZED VIEW that lets you change the query definition or add columns. You can tweak settings like materialized_only, but the underlying query is immutable.

That said, the hierarchical aggregate approach I mentioned earlier does offer some flexibility here. If I'd planned things out with stacked aggregates (raw → 15m → 1h → daily), I could have added exchange grouping at one layer without rebuilding everything. Hindsight is 20/20.

What I Would Do Differently

I'm not saying continuous aggregates are the wrong tool for crypto data. When the conditions are right, they work well:

Your query patterns are fixed and known upfront
You don't need to add grouping dimensions later
Your refresh windows are carefully tested before going live

But for crypto data specifically, where new trading pairs get added constantly and query requirements change, I'd now approach it differently:

Start with the raw hypertable and good indexes before jumping to aggregates. This sounds boring, but TimescaleDB's chunk exclusion is fast. You might not need aggregates as much as you think.
Use hierarchical continuous aggregates (available since TimescaleDB v2.9) to build a chain from fine to coarse granularity: raw → 15m → 1h → daily. This lets you reuse computation at each level, improve query performance at every tier, and gives you more flexibility if requirements change.
Plan for chunk compression from day one. Older chunks should be compressed using a TimescaleDB compression policy, set it up early and don't let chunks pile up unmanaged.
Manually call refresh_continuous_aggregate to validate your aggregate design before setting up automated policies. Debugging a broken policy after the fact is painful.
Limit the total number of aggregates. More views means more chunks, more refresh jobs, and more things to get out of sync.

The documentation frames continuous aggregates as a "set it and forget it" solution. They're not. They're a commitment to a specific query shape, and that shape is hard to change later. Go in with your eyes open.

When Exchanges Lie: Outlier Detection Across 150+ Crypto Data Sources

Asaduzzaman Pavel — Wed, 15 Apr 2026 01:41:00 +0000

A few years ago I was working on a global market data platform. The job was straightforward on paper: integrate as many cryptocurrency exchanges as possible, aggregate their price and volume data, serve it reliably. We got to around 150 exchanges. That's when things got interesting.

I expected noise. APIs go down, timestamps drift, small exchanges have thin order books. That's just how it is. What I did not expect was how many exchanges were not just noisy, but actively wrong in ways that were hard to call accidental.

Here's what I ran into.

The Web Traffic Problem

The first signal that something was off had nothing to do with price data. It was Alexa rankings.

If you're not familiar, Alexa was a web traffic ranking service. It ranked websites by how much traffic they received. Imperfect, but external, independent, and hard to game without actual users. We started cross-referencing exchange-reported volume against their Alexa rank as a basic sanity check.

The pattern was immediate. Exchanges claiming hundreds of millions in daily volume sometimes had Alexa ranks in the millions, putting them somewhere between a niche hobbyist blog and a small regional news site. Real exchanges with real users have real web traffic. Fake volume does not come with fake visitors.

How I handled it: Computed a volume-to-traffic ratio for every exchange and compared it against the median ratio across all exchanges. Anything beyond a few standard deviations from that median got a reduced trust weight. Not a hard ban, just enough drag that a lying exchange could not move the aggregate on its own.

It became one of our most reliable filters. Not because it was precise, but because it was orthogonal. An exchange can manipulate its own API. It cannot manufacture a credible web presence overnight.

Alexa shut down in May 2022. If I were building this today I'd use SimilarWeb for the same purpose. Same principle: use external signals the exchange doesn't control.

Stale Data Served Fresh

Some exchanges would return data with a current timestamp but the underlying numbers hadn't changed in minutes. Sometimes longer.

This one could be a bug. Caching misconfiguration, a stuck worker, a failed background job. But it happened too consistently on too many exchanges to feel entirely accidental. At the very least, it was a bug they had no interest in fixing.

How I handled it: Each time I polled an exchange, I hashed the price and volume payload. If the hash matched the previous several responses but the timestamp had changed, I marked it stale. After enough consecutive stale responses, I pulled that exchange out of the live feed entirely until fresh data came through. Simple, cheap, and it worked. Real markets move. If your data is not moving, it's not real.

Price Hallucination

This is different from a price slightly off due to liquidity differences. Every exchange has its own order book, so minor variance is expected and fine.

Price hallucination is when an exchange quotes a price that has no relationship to what's happening anywhere else. Not slightly off. Structurally wrong. BTC trading at $30,000 when every other exchange has it at $43,000, and it's been that way for hours.

These prices never corrected through arbitrage because there was no real liquidity behind them. Nobody was actually trading at those prices. The exchange was just publishing a number.

How I handled it: Median absolute deviation across all exchanges for the same trading pair. MAD is the right tool here because it is resistant to manipulation. To move the median you need to control the majority of your data sources, which is hard when you are pulling from 150 places. Anything more than three times the MAD from the median got excluded from that price calculation entirely. The threshold sounds arbitrary but in practice it was conservative enough to catch real hallucinations while leaving legitimate variance alone.

Ghost Liquidity

Order books that look healthy until you try to use them.

On paper: $2M sitting on the bid, $2M on the ask, tight spread. Looks like a functioning market. In practice: the moment a real order touches that book, the liquidity vanishes. Bids and asks that were sitting there seconds ago are gone.

This one is particularly cynical because it's designed specifically to fool aggregators and ranking tools that look at order book depth as a quality signal. The order book is theater. It exists to look good in screenshots and API responses, not to fill trades.

How I handled it: Real order books fluctuate constantly. Prices shift, sizes change, levels appear and disappear. If an exchange's top order book levels had not changed in a meaningful window during active market hours, that was a flag. Combined this with a spread-to-volume ratio check. Deep books with suspiciously low spreads on low-volume pairs do not add up. Either signal alone could be a false positive. Together they are reliable.

Crawler-Aware APIs

This was the one that genuinely impressed me, in a grim sort of way.

Some exchanges were serving different data depending on who was asking. Known data aggregator IP ranges got clean, reasonable-looking data. Other IPs got inflated numbers. The exchange had modeled the fact that aggregators exist, figured out how to identify them, and was gaming the system accordingly.

How I handled it: Rotating residential proxies for verification polling. Periodically I'd re-fetch the same data from a different IP and compare the responses. Persistent divergence above a threshold meant the exchange was blacklisted from aggregation entirely. Not downweighted. Gone. There's no good-faith explanation for an exchange that shows different prices to different clients. That's not a bug you fix, it's a policy you enforce.

What This Actually Is

Outlier detection across many exchanges is not primarily a statistics problem. It is a trust problem. The standard approaches (Z-scores, IQR, median absolute deviation) are useful, but they assume your outliers are noise. Some of your outliers are lies, and lies require a different mindset.

Here's what actually worked:

Use external signals. Web traffic, app store rankings, social presence. Anything the exchange doesn't control and can't fake cheaply. SimilarWeb is the practical option today.
Weight by reputation over time. Exchanges that flag consistently get less weight. Build a scoring layer that updates as you collect data. Reputation should be earned and lost dynamically, not set once at integration time.
Consensus over mean. If 140 exchanges broadly agree and 10 do not, the 10 are your problem. The median is much harder to manipulate than the mean.
Watch for perfection. Real trading data is messy. If an exchange reports exactly $10,000,000 in volume, or produces price charts that look suspiciously smooth, that's a red flag. Markets do not round like that.
Treat divergence as intent. Noise is random. These patterns were consistent, directional, and self-serving. Once you start seeing that, you stop debugging and start filtering.

Most of this was figured out the hard way. You integrate a hundred exchanges optimistically, you start noticing things that don't add up, you dig in, and eventually you build a picture of what the data ecosystem actually looks like versus what it claims to be.

You can't unsee it once you've seen it.

Twenty Years Since My First PHP Script

Asaduzzaman Pavel — Tue, 14 Apr 2026 00:02:11 +0000

I wrote my first PHP script 20 years ago. It was a forum: the kind where users could register, post threads, reply to each other. Looking back at the code now is genuinely uncomfortable. SQL queries sitting inside HTML. No password hashing. Variables called $x and $temp and, at one point I am not proud of, $temp2. But it worked, and 16-year-old me thought that was basically wizardry.

What I Got Wrong

Pretty much everything, if I am being honest.

I concatenated user input straight into SQL queries because I had no idea what SQL injection was. Nobody had told me, and I had not thought to ask. Passwords went in as plain text because hashing seemed like something "real" developers did, not me. PHP and HTML lived in the same file because the idea of separating them had never occurred to me. Why would you?

Here is roughly what a typical page looked like:

<?php
session_start();
$user = $_SESSION['user'];
?>
<html>
<body>
<?php
$id = $_GET['id'];
$result = mysql_query("SELECT * FROM posts WHERE id = $id");
while ($row = mysql_fetch_array($result)) {
    echo "<h2>" . $row['title'] . "</h2>";
    echo "<p>" . $row['content'] . "</p>";
}
?>
</body>
</html>

No escaping anywhere. No validation. Just raw $_GET values dumped straight into a query. The fact it ran at all was luck, not skill.

What I Did Not Know I Did Not Know

Security was not even a concept in my head. I knew passwords should probably be hidden from other users, but I did not think about what "hidden" actually meant in practice. XSS, CSRF, session fixation: I had never heard any of those terms. The forum got hacked twice in its first six months. Both times I had no real understanding of how it had happened. I changed some things, crossed my fingers, and kept going.

Version control did not exist in my world either. I edited files directly on the server over FTP. If something broke, the fix was to stare at the code and try to remember what I had touched. I once overwrote the entire user authentication system with an older version and did not notice for three days. The backup was my memory, which, it turns out, is not a reliable backup strategy.

As for learning resources: PHP.net, a few forums including PHPBuilder, and other people's source code. YouTube had technically launched in 2005, but it barely mattered: internet connections were so slow that streaming video was a joke. A two-minute clip could take the better part of an hour to buffer, assuming it loaded at all. Most people I knew were still on dial-up or early ADSL that struggled to hold a connection. Stack Overflow did not exist yet (it launched in 2008), and neither did GitHub. Subversion existed, as did CVS, but nobody in my circle was using them for personal projects: version control felt like something for big teams at real companies. You figured things out by reading whatever messy code you could find and trying stuff until it stopped throwing errors.

The Function Names Still Annoy Me

PHP's function naming has always been a bit of a disaster, and it was worse in 2006. mysql_fetch_array versus mysql_fetch_assoc: similar names, different behavior, and I mixed them up constantly. htmlspecialchars versus htmlentities. Why are both of those necessary? The one that really got me was strpos. It returns false if the substring is not found, but returns 0 if it is found at position zero. So if (strpos($str, 'foo')) silently fails when the match is right at the start. You have to use === false to be safe. I spent an embarrassing number of hours on that specific bug.

The language did not help beginners understand this stuff. It still has rough edges, honestly, but at least now there are tools like PHPStan and Psalm that catch a lot of it before you ship.

What I Would Tell 2006 Me

Do not panic about making it perfect. Your code is going to be rough regardless, and that is fine. Write it, ship it, break it, fix it. That loop is where the actual learning happens.

Do panic about SQL injection, though. Not later. Now. Use prepared statements. They look scarier than they are. Learn them before you get hacked a third time.

Stop naming variables $temp. I know it feels fine in the moment, but three weeks later you will have four of them and no idea what any of them hold. Two extra seconds on a real name ($userId, $postContent) saves a lot of confusion later.

FTP is not a backup. Learn version control, something like Git or SVN. I know it seems like overkill: a whole version control system, just for you, just for a hobby forum? But it is not overkill. These tools are free, they run fine on your local machine, and the basic workflow is not that complicated once you get past the initial setup. You will understand exactly why it matters the first time you accidentally overwrite something important and have nothing to go back to. That moment will come. It is better to be ready for it.

Where It Ended Up

That forum is long gone: I took it down sometime around 2008, when the server bill stopped feeling worth it for 40 active users. But I think about it sometimes. Every bad decision in that codebase taught me something. The hack that I could not explain pushed me to finally understand how injection attacks actually worked. The lost authentication system made version control feel urgent rather than optional.

Twenty years on, I am still writing code. The stack has changed completely. But the basic rhythm has not: build something, watch it break in ways you did not expect, understand why, do better next time. The forum was a mess. It was also probably the most educational thing I have ever built.

Atomic Operations in Go

Asaduzzaman Pavel — Sun, 12 Apr 2026 18:25:10 +0000

I used to think sync.Mutex was the only way to make Go concurrency safe, until I had to trace a performance cliff in a high-throughput websocket server. Turns out, parking and waking goroutines has a cost. Atomic operations in Go let you bypass the scheduler entirely and lean directly on the CPU for lock-free programming.

The hardware behind atomic operations in Go

You already know counter++ is actually a read, an add, and a write. If two goroutines do it at once, you lose an increment. Data race.

Atomics fix this using CPU-level instructions (like LOCK XADD on x86). The CPU locks the memory bus for that specific address just long enough to do the read-modify-write. No scheduler, no kernel context switch. It just happens.

One of the most frustrating things about the sync/atomic package pre-Go 1.19 was the lack of type safety. You'd pass pointers to int64 and hope you didn't accidentally pass a regular int or a 32-bit integer on a 32-bit architecture and panic at runtime. The typed API fixed this, mostly.

The modern API

Go 1.19 gave us typed wrappers. I almost never use the raw atomic.AddInt64 functions anymore. The typed API is just cleaner and prevents stupid pointer mistakes.

var counter atomic.Int64

counter.Add(1)
counter.Store(10)
counter.Load() // 10

var ptr atomic.Pointer[Config]
ptr.Store(&Config{Timeout: 5})

The full set of wrappers available now:

Type	Description
`atomic.Int32` / `atomic.Int64`	Signed integer counters
`atomic.Uint32` / `atomic.Uint64`	Unsigned integer counters
`atomic.Uintptr`	Unsigned integer pointer types
`atomic.Bool`	Boolean flag
`atomic.Pointer[T]`	Generic pointer to any type
`atomic.Value`	Any type, as long as the concrete type is consistent

Which brings me to atomic.Value

I assumed atomic.Value was just a generic bucket, but it has a nasty trap: the concrete type you store the first time locks it in forever.

var v atomic.Value
v.Store(map[string]int{"a": 1})

// This panics!
v.Store(struct{ Name string }{"bad"})

The documentation mentions this, but it's easy to miss until your app crashes in production because someone tried to store a nil error interface when it previously held a concrete error type. I've been bitten by this exact thing. If you know the type upfront, atomic.Pointer[T] is infinitely better.

A practical look at CAS loops

Compare-and-Swap (CAS) is the weirdest pattern if you're exploring mutex alternatives. You don't lock, you try to update, and if someone else beat you to it, you loop and try again.

Here's how I actually use it for rate limiting:

type RateLimiter struct {
    count  atomic.Int64
    maxRPS int64
}

func (r *RateLimiter) Allow() bool {
    for {
        current := r.count.Load()
        if current >= r.maxRPS {
            return false
        }
        // Did anyone change count since we loaded it?
        if r.count.CompareAndSwap(current, current+1) {
            return true
        }
        // Yes, they did. Loop and try again.
    }
}

This blew my mind the first time I wrote it. The loop isn't spinning endlessly; it only retries if there's actual contention at that exact nanosecond.

Config hot-reloads without pausing

Replacing a config struct while the app is running is where atomic.Pointer[T] shines. A sync.RWMutex works, but every reader has to interact with the lock state.

type Server struct {
    config atomic.Pointer[Config]
}

func (s *Server) UpdateConfig(cfg *Config) {
    s.config.Store(cfg)
}

func (s *Server) handleRequest() {
    cfg := s.config.Load() // Always gets a complete, consistent config
    _ = cfg.Timeout
}

I think this might just be my favorite use case. You do all the heavy lifting of parsing and validating the new config off to the side, and the actual update is a single atomic pointer swap. No readers block. No partial reads.

When to just use a Mutex

If your update touches more than one variable, or involves complex conditional logic spanning multiple fields, stop trying to be clever.

I spent two days trying to coordinate three atomic.Int64 counters to track queue states without locks. It was a buggy, unreadable mess. A simple sync.Mutex solved it in five minutes. Atomics are for single, isolated values. If state A depends on state B, wrap them in a mutex.

Home Assistant Works Great Until It Doesn't: 10 Years of Lessons

Asaduzzaman Pavel — Sun, 12 Apr 2026 00:38:58 +0000

My bathroom light turned on at 3 AM last Tuesday. Not because of a motion sensor. Because a template sensor I'd written eighteen months earlier, something that checked whether the sun had set and combined it with a binary input, started evaluating differently after an update changed how trigger_time_only behaves in time-based templates. The logic was identical. The behavior wasn't. I debugged YAML until 4 AM.

That's what Home Assistant ownership actually looks like.

I got into home automation the way a lot of people my age did: by building something that barely worked and being completely obsessed with it anyway. My first attempt was an Arduino driving a relay to control a lamp. It worked about 60% of the time and had a floating pin that occasionally turned the lamp on at random. I considered this a success. I considered this a success. So when I stumbled onto Home Assistant in 2016, by then already three years old and with a serious community behind it, it felt like everything I'd been groping toward.

I want to be upfront about my bias: this was always a hobby first. I did not approach it the way a normal person approaches their thermostat. I approached it the way someone approaches a long-running side project they will never fully finish. That colors everything that follows.

When the vendor pulls the rug

Nobody warns you about this one clearly enough. Companies change their APIs, sometimes overnight, and your devices stop working without any notice to you.

My smart thermostat ran flawlessly for two years. Then the manufacturer pushed a "platform upgrade" and the Home Assistant integration broke. The maintainer was a volunteer with a day job and a kid. It took three weeks to get a fix merged. I had no programmatic thermostat control for three weeks in February. I kept the heat running manually and bought a dumb programmable thermostat as backup that same week. Best $30 I spent on this system.

This pattern repeats constantly. MyQ garage doors had their local API locked down. Various Tuya-based plugs changed their cloud handshake. A weather service I used switched authentication methods. The "local control" promise is real for many devices, but even local devices often phone home for firmware updates that can change behavior or add cloud-required authentication where there was none before. The only real protection is choosing devices with well-documented local protocols: Zigbee, Z-Wave, proper Matter implementations. Treat anything that needs a cloud handshake as temporary.

2.4 GHz in a dense apartment is not a solvable problem

I live in an apartment. A 2.4 GHz scan shows somewhere around forty-seven neighboring networks, depending on the day.

My ESP32-based sensors drop offline unpredictably. Not due to bad code, not due to bad hardware. The 2.4 GHz band is saturated. I have a bedroom sensor that loses connectivity for hours at a stretch when my downstairs neighbor apparently runs something particularly RF-noisy. I never nailed down exactly what. Could be a microwave, could be a baby monitor, could be a cheap router blasting on a wide channel.

I tried everything in the ESPHome toolkit: static IP reservations (in the router, not the firmware), wifi_reboot_timeout, fast_connect: true, placing the access point as close as physically possible. The ESPHome community was genuinely helpful, but the conclusion was always the same: 2.4 GHz in dense housing is a contested shared resource. There's no fix. You manage it, you don't solve it.

For critical sensors, anything feeding an automation I'd actually notice failing, I switched to Zigbee or Z-Wave. WiFi ESP32 devices now handle non-critical monitoring only: temperature logging, power sensing, things where an hour of missed readings doesn't matter.

Zigbee's real interference problem

Zigbee is supposed to solve the WiFi reliability problem. Separate protocol, mesh self-healing, lower power, designed for exactly this use case. In a detached house with a single router, it probably works beautifully.

The catch: Zigbee also runs on 2.4 GHz, and its channel numbering is independent from WiFi's. WiFi channels 1, 6, and 11, the standard non-overlapping set most routers use, overlap directly with Zigbee channels 11 through 22. If your coordinator is sitting on Zigbee channel 11 and your neighbor's router is blasting on WiFi channel 1, they're fighting over the same frequencies. Zigbee loses, because it transmits at much lower power.

The right move, which I didn't do when I set up my network, is to pick a Zigbee channel before pairing any devices, based on a scan of the local WiFi environment. Zigbee channels 25 and 26 sit above the standard WiFi interference window entirely, though not all devices support channel 26, and channel 25 can catch the upper sideband of WiFi channel 11. Channel 15 or 20 are reasonable middle choices if your neighbors are mostly on WiFi channels 1 and 6. The problem is that changing your Zigbee channel after the fact requires re-pairing every device on the network. I've done this twice. It's a full weekend project with forty devices.

Even with a well-chosen channel, I still get ghost dropouts. A sensor shows "unavailable" for forty minutes, then comes back with no log entry explaining why. Aqara, IKEA Tradfri, and Third Reality devices all exhibit this to varying degrees. I've learned to set a considered_unavailable timeout of several hours on non-critical sensors so I'm not getting 2 AM notifications about a bathroom motion sensor that'll be back by morning.

My coordinator is a Sonoff ZBDongle-E. One thing that genuinely helped was mounting it on a USB extension cable away from the PC's USB 3.0 ports. USB 3.0 is a known source of 2.4 GHz interference due to its switching frequency. That's the kind of thing you find buried in a Zigbee2MQTT GitHub issue at midnight.

The stack is genuinely large

My current setup:

Proxmox - host os
Home Assistant Core: the main application
MariaDB: for long-term history (SQLite bogs down past a few weeks with many sensors)
Zigbee2MQTT: I switched from ZHA after the 2023.6 incident; Z2M's device support and debug tooling is better
Mosquitto: the MQTT broker Z2M talks through
ESPHome: for custom ESP32/ESP8266 devices
Several HACS integrations, including one I should probably have replaced by now
Node-RED, for automations complex enough that Home Assistant's native automation editor becomes painful

Every single component in that list has broken at some point. Not all at once, usually, but in combination. When a Zigbee device goes unavailable, I now run through a checklist: is the Z2M add-on running? Is the MQTT broker running? Is the coordinator physically connected (it works loose sometimes)? Is it just this device or all of them? Is this a Z2M issue or a Home Assistant entity issue? That diagnostic process takes five to ten minutes before I even start fixing anything.

Some automations that actually run reliably:

Power monitoring via IotaWatt on my breaker panel. I get notifications when the dryer cycle ends and alerts when the AC runs for more than ninety minutes straight. IotaWatt has a local HTTP API and has never needed a cloud service. It's the most reliable thing in my stack.
Motion-based lighting throughout the apartment. Bathroom lights on when occupied, hallway at 20% brightness after 9 PM. These work about 95% of the time. The other 5% is Zigbee flakiness.
Alexa voice control via the Home Assistant Alexa integration. I exposed my instance via a reverse proxy and custom skill.
Printer head maintenance: if I haven't printed in two days, HA triggers a test page via the Brother integration. Genuinely useful and has saved one printhead.

One automation I gave up on entirely: presence detection. I tried the companion app with GPS zones, Bluetooth beacon tracking with an ESP32 in monitor mode running room-assistant, WiFi device tracking via the Unifi integration, and a combination approach. Every method had failure modes that made it unsuitable for driving "lights off when nobody's home" logic. The GPS approach turned the lights off when my phone's location services throttled. The Bluetooth approach worked until it didn't, with no clear pattern. I now use motion sensors with a 30-minute timeout as a proxy for occupancy. It's a compromise, but it's reliable.

The 2023.6 weekend

A few months ago a DNS misconfiguration meant Home Assistant couldn't resolve the MQTT broker by hostname. I'd never set up a local DNS entry; I'd been relying on the Supervisor's internal hostname resolution, which changed behavior in an OS update. Fixed it by hardcoding the IP. Minor, but the kind of thing where you need to know what DNS resolution is to even begin troubleshooting your coffee maker.

That was minor compared to June 2023. I updated to 2023.6.1 on a Saturday morning. Within an hour, every Zigbee device in the apartment showed "unavailable." The ZHA integration had a breaking dependency change in how it handled the zigpy library version. The GitHub issue documenting it existed, but it wasn't in the release notes in a way that would have caught my attention. The community forum was immediately full of people with the same problem.

I spent most of that weekend factory-resetting and re-pairing forty devices. Some pairings required removing the device from the network first via the coordinator, then resetting the physical device, then re-interviewing it. Aqara devices have a reset procedure that involves pressing a button a specific number of times within a specific window. I looked up that procedure for maybe fifteen devices over the course of two days. My wife asked at some point why I was doing this instead of being present on the weekend. I didn't have a good answer.

That incident is part of why I switched from ZHA to Zigbee2MQTT. Z2M stores its device database independently of Home Assistant, so a HA update can't invalidate your pairings. The separation has been worth the added configuration complexity.

The time cost is the real cost

Home Assistant is free software. The hardware is not expensive. Time is the real currency here.

I've tracked my troubleshooting hours fairly carefully for the past few years. I started logging them after the 2023.6 incident because I was curious. It averages out to roughly two hours a week, but that average hides a very skewed distribution. Most weeks are zero. Weeks with major updates or unusual failures are ten-plus hours. Over ten years, conservatively, I've spent more than 500 hours keeping this system operational. That's a significant fraction of a year of working time, for a system that still fails in ways I can't predict.

The community framing is that this time buys you privacy, local control, and flexibility unavailable anywhere else. That's true. What's less often said is that it also buys you a part-time job as sysadmin for your apartment.

Living with people who didn't sign up for this

My wife and daughter have no patience for my hobby. When the bathroom light turns off mid-shower because the motion sensor lost Zigbee connection, I hear about it. When the "goodnight" routine fails to run because MQTT had a hiccup, I hear about it. My daughter learned to flip the hallway switch twice to get the light to stay on. First flip turns it on, the second forces Home Assistant to register the state change so the automation does not turn it back off. She figured this out at age eight. No twelve-year-old should have to debug state machines to use the bathroom at night.

My parents visited once. My dad stood in the living room and said, pretty reasonably, "turn on the lights." Nothing happened. Alexa requires the exact invocation; you can't just talk at the room. He looked at me like I'd made something worse than what existed before. He still mentions it.

The system works beautifully when everyone using it understands its quirks and limitations. That's not most people. Most people want the light to turn on when they flip the switch, and they don't want to learn which switch in which mode causes which state drift in the automation engine.

How the alternatives actually compare

Platform	Approximate Cost	Reliability	Customization	Privacy	Best For
Home Assistant	Free (hardware separate)	6/10	10/10	10/10	Hobbyists willing to maintain a stack
Hubitat	~$130–150	8/10	7/10	8/10	Local control without managing a server
SmartThings	~$100	7/10	6/10	4/10	Samsung ecosystem, accepts cloud dependency
Apple HomeKit	Built into iOS	9/10	5/10	9/10	Apple users who want basics to just work
Amazon Alexa	~$50	7/10	4/10	2/10	Voice-first, not privacy-focused

Home Assistant wins on customization and privacy. It loses on reliability and on what I'd call operational overhead. The amount of ongoing attention the system requires to stay functional. Hubitat is the closest thing to Home Assistant for people who want local control without maintaining a multi-service stack. HomeKit, if you're in the Apple ecosystem and your use case is relatively simple, has dramatically better day-to-day reliability.

Who should actually run this

Run Home Assistant if:

Troubleshooting is something you find engaging rather than draining
You can reliably spare a few hours most weeks, and sometimes an entire weekend
Privacy and local control are genuinely non-negotiable for you
You're treating this as a hobby, not a utility
You have reasonable Linux/networking knowledge. Not expert level, but enough to know what a YAML syntax error looks like and what DNS does

Skip it if:

You want the lights to reliably work
You live with people who didn't opt into a temperamental system
You'd rather spend free time on other things
You need presence detection to function
Technology failing unexpectedly is something you find genuinely stressful

Where I've landed

I'm not migrating off Home Assistant. The IotaWatt integration alone is worth staying for, and I've built enough custom logic over the years that rebuilding it elsewhere would be its own project. But I've significantly dialed back my ambitions for what the system should do.

Nothing safety-critical runs through Home Assistant. Every light has a physical switch that works independently of network state. The thermostat has a manual override. When the smart garage opener died, I went back to the original remote and didn't replace it with anything smart.

If I were starting from scratch today, I'd buy far fewer devices and be much more selective about protocols. Everything on the critical path would be Zigbee or Z-Wave with known-good local support, deployed on a carefully chosen channel, with the coordinator on a USB extension cable away from noisy USB 3.0 ports. I'd skip presence detection entirely. I'd probably use a Home Assistant Green instead of building my own box. The $99 hardware is worth not debugging SD card corruption.

The honest version is this: the automated home as it exists in practice is still a project, not a product. For some people that's the appeal. For most people, it's a reason to buy smart bulbs that work with HomeKit and leave it at that.

The Only Prometheus Metrics I Actually Alert On

Asaduzzaman Pavel — Sat, 11 Apr 2026 16:40:43 +0000

I used to instrument everything. Every function call, every cache hit, every database query. My Prometheus instance was ingesting somewhere north of 50,000 samples per second across three services, and I thought that density meant rigor. Then our checkout flow went down at 3 AM during a sale event, and I spent twenty minutes scrolling through dashboards before I found the single metric that mattered: connection pool exhaustion on the payments database. It had been queuing for six minutes before queries started timing out. I had a metric for it. I just wasn't alerting on it.

That's the gap this post is about. Not the theoretical list of things you could track, but what I've found worth waking up for.

Golden Signals are a starting point, not an answer

Google's four Golden Signals (latency, traffic, errors, saturation) point you in the right direction. But they're underspecified enough that following them naively leads to useless alerts.

Latency without percentiles tells you nothing actionable. If your p99 is 2 seconds and your mean is 50ms, the mean is actively misleading. Users hit the tail, not the average. I track p50, p95, p99, and max. The gap between p95 and p99 is often the most interesting number. A large gap usually means a specific slow path (a missing index, a lock contention, an N+1 query) rather than a general performance problem.

Errors need to distinguish user-visible failures from internal retries. A database timeout that triggers a retry and eventually succeeds is not the same failure mode as a 500 returned to the user, but both increment error counters in most client libraries by default. I split by severity: critical for user-visible failures, warning for degraded-but-functional, and info for retried-successfully events. Only critical fires a page.

What I actually instrument in HTTP services

I instrument at the edge, a single middleware or handler wrapper, so every endpoint gets consistent labels automatically. Three metrics:

http_requests_total{method, path, status}
http_request_duration_seconds{method, path, status, le}
http_in_flight_requests{method, path}

http_requests_total gives you rate and error ratio. The histogram gives you latency at any percentile. In-flight requests catch saturation before it shows up in latency. By the time requests slow down, you've usually been saturated for a while.

The mistake I made early on: I used the full request path as a label, so /users/12345/profile and /users/67890/profile became separate time series. At any meaningful user count, cardinality explodes and Prometheus runs out of memory. Sanitize paths before labeling. Replace ID segments with a placeholder like /users/{id}/profile. This is obvious in retrospect but I've seen it sink three separate teams' setups.

For gRPC, same pattern, but I add grpc_code as a label. gRPC status codes are more expressive than HTTP codes (RESOURCE_EXHAUSTED vs UNAVAILABLE vs DEADLINE_EXCEEDED all have different remediation paths), and I reference them directly in alert conditions.

Database metrics: the failure mode that sneaks up on you

Connection pool exhaustion is the failure mode that hurts most and is hardest to detect early. By the time queries are timing out, you've been at capacity for minutes. These come from the application, not the database server:

db_pool_connections_active
db_pool_connections_idle
db_pool_connections_wait_count_total
db_query_duration_seconds{query, le}

The wait count is your leading indicator. I alert when rate(db_pool_connections_wait_count_total[5m]) > 0, but I treat it as a warning, not a page. Brief queuing can happen under bursty traffic without indicating a real problem. Sustained queuing (for more than a few minutes) usually means an undersized pool or a connection leak. The alert tells me to look; I don't automatically assume the worst.

Query duration histograms need custom buckets. Default client library buckets assume sub-second operations, but a report query or a schema migration step might legitimately take 30 seconds. I use: 0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0, 30.0. If your query durations don't fit this range, adjust. The buckets should bracket your actual distribution.

Server metrics: what node_exporter exports vs. what matters

Node exporter exports 700+ metrics by default in current versions (and more with optional collectors enabled). Most are noise for application operators. The ones I use consistently:

node_cpu_seconds_total: CPU utilization via rate()
node_memory_MemAvailable_bytes: not MemFree; available includes reclaimable cache and gives a realistic picture of OOM risk
node_filesystem_avail_bytes: disk space
node_load1: secondary signal, never primary

When I care about CPU, I filter by mode. iowait indicates a disk-bound process; steal in virtualized environments indicates you're competing with other tenants for CPU time. User and system time being high is expected. Iowait and steal are the modes that suggest something is wrong upstream of your application.

The Alertmanager config I wish I'd started with

My first Alertmanager config routed everything to a single Slack channel. During a cascading failure, I received 400 messages in 10 minutes and missed the root cause entirely. The cascade was loud enough to bury the signal. Here's the structure I've settled on:

route:
  group_by: ['alertname', 'cluster', 'severity']
  group_wait: 30s
  group_interval: 5m
  repeat_interval: 12h
  receiver: 'default'
  routes:
    - matchers:
        - severity = critical
      receiver: pagerduty
      continue: true
    - matchers:
        - severity = warning
      receiver: slack
      group_interval: 30m

flowchart TD
    A[Prometheus fires alerts] --> B[Alertmanager]
    B --> C[Alert Processing]
    C --> D[Deduplication]
    C --> E[Grouping by alertname, cluster, severity]
    C --> F[Apply Silences]
    D --> G[Route to Receivers]
    E --> G
    F --> G
    G -->|severity=critical| H[PagerDuty]
    G -->|severity=critical + continue=true| I[Slack]
    G -->|severity=warning| J[Slack batched 30m]
    G -->|severity=info| K[Slack batched 30m]
    H --> L[Wake someone up]
    I --> M[Channel context]
    J --> N[Look in business hours]

Critical alerts hit PagerDuty immediately. Warnings batch into 30-minute windows. This prevents alert fatigue while keeping urgent pages urgent.

Alert fatigue is real. When everything pages, nothing pages. Teams start muting notifications because they can't sleep, and then the alerts that matter get buried too. Better to have three alerts you actually respond to than thirty you've learned to ignore.

The continue: true on the critical route matters. Without it, a matching route stops processing entirely, so critical alerts would never reach Slack. I want them in both places: PagerDuty wakes someone up, Slack gives the channel context.

A practical warning: Alertmanager's matching syntax changed meaningfully between versions. Before v0.22, you use match: and match_re: as maps. From v0.22 onward, the recommended syntax is matchers: with a list format. In practice, many deployments run mixed versions. The docs you find may not match what you've deployed. Check your version first.

Recording rules: when complexity pays off

Recording rules pre-compute expensive queries and make dashboards and alerts faster. I use them in two situations: when a query takes more than a second to evaluate, and when I reference the same complex expression in multiple alerts or dashboards. Outside those two cases, they add complexity without payoff.

groups:
  - name: http_rates
    interval: 30s
    rules:
      - record: job:http_requests:rate5m
        expr: sum(rate(http_requests_total[5m])) by (job)
      - record: job:http_errors:rate5m
        expr: sum(rate(http_requests_total{status=~"5.."}[5m])) by (job)

With those recorded, the error ratio alert simplifies to:

- alert: HighErrorRate
  expr: job:http_errors:rate5m / job:http_requests:rate5m > 0.01
  for: 5m

Without recording rules, that division across all time series can time out on high-cardinality metrics. Whether you need recording rules at all depends on your scale. At small cardinality, raw queries work fine.

Alert thresholds and avoiding false positives

Every alert I write includes a for: duration. An instant threshold crossing is almost always a deployment blip, a brief GC pause, or a transient spike. Not something worth paging about. I use 5 minutes for error rate and latency, 10 minutes for saturation and capacity, and 0 minutes only for complete outages or security events.

I include a severity label in every alert. Without it, Alertmanager can't route correctly. Critical means wake someone up. Warning means look at it during business hours. Info means log it.

What I stopped monitoring

I don't alert on memory usage anymore. High memory isn't a problem, OOM is. For containers, alert on container_oom_events_total from cAdvisor. For VMs or bare metal, watch the OOM killer logs. Memory pressure without OOM is usually just efficient caching.

I don't alert on disk I/O wait directly. I alert on latency increases that correlate with high iowait. The user pain is the latency, not the disk activity.

I don't use predictive disk fill alerts ("disk will fill in 4 hours"). They generate false positives during batch jobs and log rotations without giving you actionable signal. Instead, I alert at 85% capacity with a 1-hour for: duration. This is a simpler threshold, but it assumes you're monitoring write rates separately for services where fill speed matters. If a service can fill a disk in under an hour, 85% may not give you enough runway, and you'd want to tighten the threshold or add a rate-based rule.

Grafana: dashboards for humans under pressure

When I get paged at 3 AM, I need to understand what's broken in under 30 seconds. That's the design constraint. My main dashboard has four panels: request rate (QPS), error rate percentage, p99 latency, and active alerts by severity. Everything else lives on sub-dashboards, linked from variable-based drill-downs.

A few things I've found useful beyond the basics: variable-based filtering lets you scope a dashboard to a single service or cluster without duplicating it. Template variables with $job and $instance selectors give you one dashboard that works across all your services. I also keep a separate dashboard for saturation signals: connection pool utilization, thread pool depth, queue length. These are leading indicators I want to check when latency starts rising but errors haven't followed yet.

For the panels themselves, I use recording rule data rather than raw metrics. Dashboards render faster and the difference in precision doesn't matter for human-readable trend graphs.

The cardinality trap

High cardinality is the most common way to break Prometheus. Each unique label combination creates a new time series. At scale, 1,000 pods each exporting 100 metrics with 10 label combinations, you reach 1 million series quickly, and Prometheus's memory usage grows roughly linearly with series count.

My constraints: no more than 5 labels per metric, no unbounded labels (user IDs, session IDs, request IDs, UUIDs), and no single metric with more than ~1,000 unique label combinations in practice.

I use prometheus_tsdb_head_series to watch my own cardinality. When it grows unexpectedly between deploys, I track down the culprit with:

topk(10, count by (__name__)({job="myjob"}))

This shows which metric names have the most series. From there, a count by (label_name) query on the offending metric usually surfaces the high-cardinality label immediately.

The Meta Tags That Matter (And the JSON-LD That Gets You Cited)

Asaduzzaman Pavel — Sat, 11 Apr 2026 10:44:15 +0000

I used to treat meta tags as an afterthought. Slap a <title> on the page, maybe add a description, call it done. Then I watched my carefully-written articles get buried in search results while thin content from bigger sites ranked above me. The difference? They spoke Google's language. I wasn't using structured data.

JSON-LD structured data and proper meta tags aren't just "nice to have" anymore. They're how you tell search engines and AI systems what your content actually means. Without them, you're trusting algorithms to guess correctly.

What Meta Tags Do

Meta tags are HTML elements that describe your page to machines. Humans never see them directly, but they determine how your page appears in search results, social shares, and AI summaries.

There are three kinds that matter: search engine metadata, social sharing metadata, and structured data.

The Non-Negotiable Search Tags

Every page needs these, full stop:

<title>Your Article Title — Site Name</title>
<meta
    name="description"
    content="A compelling 150-160 character summary that includes your primary keyword."
/>
<link rel="canonical" href="https://example.com/your-page" />

The title should be under 60 characters or Google truncates it. The description won't directly affect your ranking, but it absolutely affects whether people click. And the canonical tag prevents duplicate content issues when the same content lives at multiple URLs.

Social Sharing: Open Graph and Twitter Cards

Without Open Graph tags, social platforms just guess what to show. You'll get random images and truncated titles.

<!-- Open Graph (Facebook, LinkedIn, etc.) -->
<meta property="og:title" content="Your Article Title" />
<meta property="og:description" content="Description for social shares" />
<meta property="og:image" content="https://example.com/og-image.jpg" />
<meta property="og:url" content="https://example.com/your-page" />
<meta property="og:type" content="article" />

<!-- Twitter/X Cards -->
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:title" content="Your Article Title" />
<meta name="twitter:description" content="Description for Twitter" />
<meta name="twitter:image" content="https://example.com/twitter-image.jpg" />

Use summary_large_image for Twitter if you have a good featured image. The regular summary card is smaller and less engaging. And yes, you still need to call them Twitter Cards — that's what the specification is named even though the company is now X.

JSON-LD: Structured Data That Gets You Featured

JSON-LD (JavaScript Object Notation for Linked Data) is the format Google recommends for structured data. It's a script block that tells search engines exactly what entities are on your page.

What got me interested: pages with proper structured data get featured snippets, rich results, and knowledge panel entries. Rotten Tomatoes saw a 25% higher click-through rate after adding structured data. The Food Network got a 35% increase in visits. It actually works.

Multiple Image Aspect Ratios

Most people just slap one image in their structured data. But Google recommends multiple aspect ratios — 16:9 for rich results, 4:3 for standard displays, and 1:1 for square crops.

My BlogPosting schema handles this automatically:

schema.image = [
    `${siteBaseUrl}${post.coverImage}`, // Original (typically 16:9)
    `${siteBaseUrl}${post.coverImage.replace(/\.(png|jpg|jpeg|webp)$/i, '-1x1.$1')}`, // 1:1 square
    `${siteBaseUrl}${post.coverImage.replace(/\.(png|jpg|jpeg|webp)$/i, '-4x3.$1')}` // 4:3 standard
];

If the post doesn't have a cover image, it falls back to dynamically generated OG images with the same aspect ratio options. Your content looks right whether it appears in Google's rich results, Twitter cards, or LinkedIn shares.

ProfilePage Schema

For my homepage, I use Google's ProfilePage structured data — a relatively new schema type specifically designed for personal websites and author pages:

export function generateProfilePageSchema(postsCount?: number) {
    return {
        '@context': 'https://schema.org',
        '@type': 'ProfilePage',
        dateCreated: '2024-01-15',
        dateModified: '2026-04-11',
        mainEntity: {
            '@type': 'Person',
            name: 'Your Name',
            jobTitle: 'Software Engineer',
            image: [
                'https://example.com/photo.jpg', // 1:1 headshot
                'https://example.com/og-16x9.jpg', // 16:9 banner
                'https://example.com/og-4x3.jpg' // 4:3 alternative
            ],
            sameAs: [
                'https://github.com/username',
                'https://linkedin.com/in/username',
                'https://twitter.com/username'
            ],
            // This part is interesting:
            agentInteractionStatistic: {
                '@type': 'InteractionCounter',
                interactionType: 'https://schema.org/WriteAction',
                userInteractionCount: postsCount // e.g., 42
            }
        }
    };
}

The agentInteractionStatistic with WriteAction tells Google how many posts you've written. When someone searches for your name, they might see "42 posts" in your knowledge panel. That's social proof in search results.

BlogPosting Schema: Author and Publisher

Google has specific guidelines for authorship markup. You need both an author (the Person who wrote it) and a publisher (the Organization responsible for it). Even on a personal blog, you're both:

export function generateBlogPostingSchema(post: Post) {
    return {
        '@context': 'https://schema.org',
        '@type': 'BlogPosting',
        headline: post.title,
        description: post.description,
        author: {
            '@type': 'Person',
            name: authorName,
            url: siteBaseUrl,
            sameAs: authorSameAs // Links to GitHub, LinkedIn, etc.
        },
        publisher: {
            '@type': 'Organization',
            name: authorName,
            url: siteBaseUrl
        },
        datePublished: '2026-04-11T08:00:00+00:00',
        dateModified: '2026-04-11T10:00:00+00:00',
        // ISO 8601 duration format for reading time
        timeRequired: 'PT8M' // 8 minutes
    };
}

The sameAs array matters — it connects your content to your established presence on GitHub, LinkedIn, Twitter, etc. Google uses these E-E-A-T (Experience, Expertise, Authoritativeness, Trustworthiness) signals for ranking.

FAQ Schema for "People Also Ask"

If you want to capture featured snippets, FAQ schema is your best bet:

export function generateFAQSchema(items: FAQItem[], post: Post) {
    return {
        '@context': 'https://schema.org',
        '@type': 'FAQPage',
        mainEntity: items.map((item) => ({
            '@type': 'Question',
            name: item.question,
            acceptedAnswer: {
                '@type': 'Answer',
                text: item.answer
            }
        }))
    };
}

Keep answers to 40-60 words. Longer answers get truncated or ignored by Google's snippet extraction. I store FAQ items in the post frontmatter and render them both visually on the page and invisibly in the JSON-LD.

Putting It All Together: The Complete SEO Component

I combine everything in a SvelteKit SEO component using $derived to reactively build metadata from props, then render it server-side so crawlers see it immediately:

<script lang="ts">
    let { title, description, post, breadcrumbs, faq, readingTime } = $props();

    // Reactively generate schemas whenever props change
    let blogPostingSchema = $derived(post ? generateBlogPostingSchema(post) : null);
    let breadcrumbSchema = $derived(
        breadcrumbs?.length ? generateBreadcrumbSchema(breadcrumbs) : null
    );
    let faqSchema = $derived(faq?.length && post ? generateFAQSchema(faq, post) : null);

    // Combine all structured data into one array
    let allStructuredData = $derived([
        ...(blogPostingSchema ? [blogPostingSchema] : []),
        ...(breadcrumbSchema ? [breadcrumbSchema] : []),
        ...(faqSchema ? [faqSchema] : [])
    ]);
</script>

<svelte:head>
    <title>{pageTitle}</title>
    <meta name="description" content={description} />
    <link rel="canonical" href={canonicalUrl} />

    <!-- Open Graph with multiple images -->
    {#if ogImages?.length}
        {#each ogImages as img}
            <meta property="og:image" content={img.url} />
            <meta property="og:image:width" content={img.width} />
            <meta property="og:image:height" content={img.height} />
        {/each}
    {/if}

    <!-- Twitter with reading time labels -->
    <meta name="twitter:card" content="summary_large_image" />
    <meta name="twitter:label1" content="Written by" />
    <meta name="twitter:data1" content={authorName} />
    <meta name="twitter:label2" content="Est. reading time" />
    <meta name="twitter:data2" content={readingTimeStr} />

    <!-- JSON-LD rendered server-side -->
    {#each allStructuredData as data}
        {@html `<script type="application/ld+json">${JSON.stringify(data)}</script>`}
    {/each}
</svelte:head>

The {@html} tag is necessary because Svelte escapes script content by default. Since the data is server-generated, this is safe.

Using the Component

In your +page.svelte, pass the data from your loader:

<script>
    import SEO from '@components/SEO/index.svelte';

    let { data } = $props();
</script>

<SEO
    title={data.post.title}
    description={data.post.description}
    post={data.post}
    faq={data.post.faq}
    readingTime={data.readingTime}
/>

That's it. The component generates all the meta tags, OG images, and JSON-LD automatically. Since it renders in svelte:head during SSR, crawlers see the complete markup without waiting for JavaScript.

When you build for Cloudflare Workers (pnpm build), the output in .svelte-kit/cloudflare/ contains static HTML with all the JSON-LD already injected. No client-side rendering required — search engine crawlers get the structured data on the first request.

A note on tooling: Google Search Console's Rich Results Test has a caching layer that can make results inconsistent — run it twice and you may get different output. More importantly, the schema.org documentation lists hundreds of properties, but only a fraction are recognized by Google. Use the Google Search Central documentation as your source of truth — it's what actually triggers rich results.

AI SEO: Why This Matters More Now

Traditional SEO gets you ranked. AI SEO gets you cited.

ChatGPT, Perplexity, and Google's AI Overviews pull from structured data when generating answers. If your content isn't marked up correctly, AI systems can't extract it cleanly. They'll cite your competitors instead.

According to Princeton's Generative Engine Optimization research, pages with proper citations and statistics get cited 40% more often by AI systems. Pages with clear structure and schema markup see 30-40% higher visibility. The same JSON-LD that gets you rich snippets also makes your content extractable for AI answers.

Testing Tools

Don't just add markup and hope. Test it:

Google Rich Results Test — Shows which features your page qualifies for. Paste a URL or raw HTML.
Schema.org Validator — Catches syntax errors and missing required fields. More lenient than Google's tool.
Facebook Sharing Debugger — Forces a scrape of your OG tags and shows exactly what Facebook sees.
Twitter Card Validator — Same for Twitter cards. Shows card type, image, and preview.

Run the Rich Results Test twice. Google's cache can lag, and the second run is often more accurate than the first.

Image Dimensions

Get the dimensions wrong and you'll end up with blurry crops or platforms ignoring your images entirely.

Platform	Optimal Size	Aspect Ratio	Notes
Twitter/X	1200×600 or 1200×1200	2:1 or 1:1	Large summary card prefers 2:1, but 1:1 also works
Facebook	1200×630	1.91:1	If you only make one OG image, make this size
LinkedIn	1200×627	1.91:1	Similar to Facebook, but slightly different
Google	1200×675	16:9	For rich results and Discover feed

Minimums to avoid rejection:

Twitter: 144×144 (they upscale, but it looks bad)
Facebook: 200×200 (anything smaller gets ignored)
Google rich results: 120×120 absolute minimum, 600×600 recommended

NixOS vs Traditional Linux: Why I Made the Switch and What I Learned

Asaduzzaman Pavel — Thu, 09 Apr 2026 22:39:09 +0000

After years of distro-hopping and watching every Linux installation slowly fall apart, I finally found my home in NixOS. What started as curiosity about a "weird functional Linux distribution" has turned into genuine enthusiasm for what might be the future of operating systems.

The Breaking Point

Like many Linux users, I had grown tired of a system I couldn't trust. I didn't need a dramatic failure to convince me. I simply wanted a Linux distribution where I could describe my entire setup in code rather than accumulating changes through countless imperative commands. Plus, knowing I could roll back instantly if I messed up a configuration gave me the confidence to experiment freely.

The traditional Linux model of imperative package management, where you run commands that mutate your system state, had failed me one too many times. I needed reproducibility, reliability, and the confidence that my system would work the same way today as it did yesterday.

Discovering the Nix Way

NixOS approaches system configuration from a radically different angle. Instead of imperatively installing packages and modifying configuration files scattered across your filesystem, you declare your entire system configuration in a single file (or set of files), just like dotfiles or Infrastructure as Code (IaC) tools like Ansible. The Nix package manager then builds your system from this declarative specification. With the introduction of Flakes, this process has become more manageable, allowing me to pin exact versions of dependencies and manage my configurations, just like dotfiles or IaC with Ansible, more deterministically across different machines.

This means your system is reproducible. You can take your configuration.nix file or your Flake configuration, just like dotfiles or an Ansible playbook to any machine and rebuild an identical system. No more "works on my machine" problems. No more forgotten configuration tweaks that break when you need to set up a new development environment.

What I Actually Like About It

Atomic Upgrades and Rollbacks

Every system configuration in NixOS creates a new generation. If an update breaks something, you can roll back to any previous generation instantly. This isn't just theoretical, I've used this feature countless times when experimenting with new configurations or testing newer software.

Isolation and Reproducibility

Development environments in NixOS are truly isolated. I can have multiple versions of Node.js, Python, or any other runtime available simultaneously without conflicts. Each project can specify its exact dependencies, and Nix ensures they don't interfere with each other or with the base system.

Configuration as Code

My entire system configuration lives in Github private GitLab repo. I can see exactly what changed between any two points in time, collaborate on configurations with teammates, and maintain separate branches for different use cases (work laptop, home desktop, and server setup).

The Learning Curve

I won't lie. NixOS has a steep learning curve.

The documentation is genuinely terrible. I never even knew the official NixOS wiki (wiki.nixos.org) existed, and it turns out it's just a fork of the unofficial, backdated wiki (nixos.wiki), which is frequently the first result on Google and adds confusion with its mix of accurate and misleading information. You'll find yourself piecing together information from unofficial Discord channels (shoutout to the server owner NobbZ for their help), YouTube videos by creators like VimJoyner and EmergentMind for their guidance, the NixOS manual, Nixpkgs manual, GitHub issues, and random blog posts just to accomplish basic tasks.

The official documentation often shows you what to do but rarely explains why or provides context for beginners. Want to understand how overlays work? Good luck finding a comprehensive explanation that doesn't assume you're already familiar with advanced concepts. Need to configure a service? The options are documented, but figuring out how they interact or what a minimal working configuration looks like often requires diving into the source code. Even Flakes and Home Manager, while powerful for managing configurations just like dotfiles or IaC with Ansible, add their own complexity, with sparse official guides that can leave newcomers struggling.

But here's the thing: once you understand the core concepts and how to structure projects, it all makes sense. The initial investment in learning pays dividends in system reliability and maintainability. I spent more time in my first month with NixOS reading documentation than I had in years of using other distributions, but I've spent far less time dealing with broken systems since then.

Practical Advantages in Daily Use

Development Workflows

Using nix-shell, I can drop into any development environment instantly. Need to quickly test something with Node.js 14 and a specific set of npm packages? One command gives you an isolated environment with exactly those dependencies. Working on a legacy project that requires an older version of PostgreSQL? No problem, it won't interfere with the newer version you use for other projects. Flakes make this even easier by letting me define reproducible development environments with pinned dependencies in a single flake.nix file.

If you're a developer wondering whether Nix plays well with your stack, yes it does. I use it with SvelteKit, Node.js, Go, Python, PHP and it just works. With nix-direnv, your dev environment activates automatically when you enter a project directory. No manual shell switching, no version conflicts, no "it worked yesterday" moments.

Server Management

For servers, NixOS is a game-changer. Your entire server configuration is versioned and reproducible. Deploying the same configuration to multiple servers is trivial. Rolling back a problematic deployment is instant. The days of manually configuring servers and hoping you remember all the steps are over.

Package Management

The Nix package repository is massive and remarkably up-to-date. Binary caches mean you rarely need to compile from source, but when you do need a custom build, Nix makes it straightforward to override package definitions or create your own.

What I Miss (And Don't Miss)

I occasionally miss the simplicity of apt install or pacman -S for quick one-off installations. In NixOS, even temporary software installs require a bit more thought, whether you want something available in your shell, user profile, or system configuration.

That said, I can still run something temporarily with comma, a small tool that lets you run any package from nixpkgs without installing it. For example, instead of nix run nixpkgs#cowsay, you just type , cowsay. It leaves no trace and no clutter.

What I don't miss is the anxiety around system updates on traditional distributions. I don't miss hunting down scattered config files under /etc. I don't miss the slow accumulation of entropy that gradually breaks things. And I definitely don't miss the "hope and pray" approach to system maintenance.

The Community

The NixOS community is small but incredibly knowledgeable and helpful. The quality of discourse is high, and there's a strong culture of documenting solutions and sharing configurations. The ecosystem around Nix is growing rapidly, with tools like Home Manager for user-level configuration management.

Looking Forward

NixOS has fundamentally changed how I think about computing environments. The confidence that comes from having a completely reproducible, version-controlled system configuration is liberating. I can experiment fearlessly, knowing I can always roll back. I can maintain complex development environments without the fear of conflicts or bitrot.

Is NixOS for everyone? Probably not. If you just want a simple desktop that works out of the box and you're happy with the defaults, Linux Mint, Ubuntu or Pop!_OS might serve you better. But if you're a developer, system administrator, or anyone who values reproducibility and reliability over simplicity, NixOS might just change your life.

Resources

If you're curious or just getting started, here are some links I found useful:

Nix Pill - classic introduction to Nix
NixOS Manual - official system documentation
NixOS Wiki - official NixOS wiki
nix.dev – practical guide for using Nix in real projects
Zero to nix - beginner-friendly intro to the ecosystem
Vimjoyer Youtube - tutorials and walkthroughs
Emergent_Mind Youtube - deep dives into Nix concepts
NixOS Discord (unofficial) - active and helpful community
My Configuration - my personal NixOS setup

Notes on Testing: Why I Prefer Testcontainers Over Mocks

Asaduzzaman Pavel — Thu, 09 Apr 2026 22:38:52 +0000

I've wasted entire Fridays writing "perfect" mocks for my database layer. I'd spend hours defining exactly what GetByID should return, only to have the app crash in production because of a missing comma in my SQL or a misunderstood Postgres constraint. That's the problem: mocks don't test your code, they test your assumptions about your code. And usually, your assumptions are wrong.

...And that's why I've mostly moved to Testcontainers. I'd rather wait ten seconds for a real Docker container to spin up than spend ten minutes faking a database behavior that I'm only 80% sure about anyway.

Mocks are just lies we tell ourselves

When you mock a database repository, you're essentially saying: "When I call GetByID, return this static struct." It's fast, sure, but it completely ignores reality. It doesn't catch syntax errors, it doesn't catch unique constraint violations, and it definitely doesn't catch the weird way your specific version of Postgres handles JSONB columns.

I've seen too many projects where the tests were 100% green but the application was broken in its core because the mock didn't account for a simple foreign key constraint. With a real container, the database does the work for you.

The CI Headache (The Real Gripe)

Look, I love Testcontainers, but setting them up in a CI environment like GitHub Actions is an absolute pain in the neck. You end up down a rabbit hole of Docker-in-Docker (DinD) configurations, permission issues, and mounting /var/run/docker.sock into a runner that really doesn't want you to have that much power.

There's always that one morning where the CI pipeline just hangs indefinitely because the runner ran out of disk space while trying to pull the postgres:16-alpine image for the hundredth time. It's a trade-off. I'm trading "clean" CI for "reliable" code, but don't let anyone tell you it's a smooth setup. It's a battle.

How I actually use it in Go

I don't restart the container for every single test. That would be insane. I spin up one instance of Postgres at the start of the test suite, and then I use a fresh database or a schema migration for each test.

func TestRepository_CreateUser(t *testing.T) {
    ctx := context.Background()

    // Real Postgres 16 container
    pgContainer, err := postgres.RunContainer(ctx,
        testcontainers.WithImage("postgres:16-alpine"),
        postgres.WithWaitStrategy(
            wait.ForLog("database system is ready to accept connections").
                WithOccurrence(2).
                WithStartupTimeout(5*time.Second),
        ),
    )
    if err != nil {
        t.Fatal(err)
    }
    defer pgContainer.Terminate(ctx)

    // Now we test against a REAL database
    connStr, _ := pgContainer.ConnectionString(ctx, "sslmode=disable")
    db, _ := sql.Open("postgres", connStr)
    repo := repository.NewUserRepository(db)

    // This will ACTUALLY fail if my SQL is broken
    err = repo.Create(ctx, &domain.User{Email: "test@example.com"})
    assert.NoError(t, err)
}

Confidence Over Speed

Yes, it's slower. But I'd rather have a test suite that takes two minutes and actually tells me the truth than a suite that takes two seconds and lies to my face. When I'm using my hand-crafted SQL approach, I need to know that my queries are valid. Testcontainers is the only way I've found to get that confidence without actually deploying to a staging environment.

It's not perfect. The local Docker-on-Mac/Windows slowness is real, and the CI setup is a constant fight, but I'm never going back to heavy mocking for my data layer. It's just not worth the risk of a 3 AM production page.

Deploying SvelteKit to Cloudflare Workers for Free

Asaduzzaman Pavel — Thu, 09 Apr 2026 22:33:35 +0000

For years, deploying a full-stack web app meant either paying for a VPS or wrestling with complex container orchestration. Cloudflare Workers changes that. You can run SvelteKit with server-side rendering, API routes, and edge caching, all without spending a dime on the generous free tier.

This guide walks through the exact setup I use for this site. No theoretical fluff, just working configuration.

What you get for free

Cloudflare's free tier is surprisingly capable:

100,000 requests/day — enough for most personal projects and small sites
10ms CPU time per request — SvelteKit runs comfortably within this
1 GB of KV storage — for simple config or session data
Custom domains — connect your own domain at no extra cost

Compare this to Vercel's hobby tier (limited to 10s serverless function duration) or Netlify's build minute limits. Workers' V8 isolate model means faster cold starts and more predictable pricing if you ever need to scale.

Prerequisites

Node.js 18+ installed
A Cloudflare account (free tier works fine)
A SvelteKit project ready to deploy

If you don't have a SvelteKit project yet:

pnpx sv create my-app
cd my-app
pnpm install

Step 1: Install the adapter

Cloudflare Workers runs JavaScript in V8 isolates, not Node.js. SvelteKit needs an adapter to bridge this gap:

pnpm add -D @sveltejs/adapter-cloudflare

The adapter-cloudflare package handles both Workers and Pages deployment. For new Workers Static Assets (the modern approach), this is the adapter you want, not the older adapter-cloudflare-workers.

Step 2: Configure svelte.config.js

Replace the default adapter in your svelte.config.js:

import adapter from '@sveltejs/adapter-cloudflare';
import { vitePreprocess } from '@sveltejs/vite-plugin-svelte';

/** @type {import('@sveltejs/kit').Config} */
const config = {
    preprocess: vitePreprocess(),
    kit: {
        adapter: adapter({
            // See below for options
            config: undefined,
            platformProxy: {
                configPath: undefined,
                environment: undefined,
                persist: undefined
            },
            fallback: 'plaintext',
            routes: {
                include: ['/*'],
                exclude: ['<files>', '<build>', '<redirects>']
            }
        })
    }
};

export default config;

Key options explained:

config: Path to your Wrangler config file (we'll create this next)
platformProxy: Controls how local bindings are emulated during development
fallback: 'plaintext' gives you a simple 404 page; use 'spa' if you need client-side routing for unmatched paths
routes.exclude: Tells Cloudflare which requests can bypass the Worker and serve static assets directly. This saves you invocation costs.

Step 3: Create wrangler.jsonc

Create a wrangler.jsonc file in your project root:

{
    "name": "my-sveltekit-app",
    "main": ".svelte-kit/cloudflare/_worker.js",
    "compatibility_flags": ["nodejs_als", "nodejs_compat"],
    "compatibility_date": "2024-09-23",
    "assets": {
        "binding": "ASSETS",
        "directory": ".svelte-kit/cloudflare"
    },
    "routes": [
        {
            "pattern": "yourdomain.com",
            "custom_domain": true
        }
    ]
}

What each field does:

name: Your Worker's identifier in the Cloudflare dashboard
main: The entry point SvelteKit generates. Don't change this.
compatibility_flags: nodejs_als is required for SvelteKit's async context; nodejs_compat helps with NPM packages that use Node.js APIs
compatibility_date: Cloudflare's runtime version. Bump this periodically for new features.
assets: Tells Workers where your static files live
routes: Connects custom domains (you can add this later if you don't have a domain yet)

Step 4: Build and deploy

Build your app locally first to verify everything works:

pnpm build

This creates a .svelte-kit/cloudflare/ directory containing your optimized app.

Now install Wrangler CLI and deploy:

pnpm add -g wrangler
wrangler login
wrangler deploy

After the first deploy, Cloudflare gives you a *.workers.dev subdomain. Free hosting, no domain required.

Step 5: Connect a custom domain (optional)

If you have a domain managed by Cloudflare:

Go to Workers & Pages in your Cloudflare dashboard
Select your Worker
Click "Triggers" → "Add Custom Domain"
Enter your domain

If your DNS is elsewhere, add a CNAME record pointing to your *.workers.dev subdomain.

Common gotchas

Node.js compatibility

Not all pnpm packages work in Workers. Anything relying on fs, native bindings, or certain Node.js internals will fail. Check the Cloudflare Workers runtime API docs before adding heavy dependencies.

If you hit issues, try adding the nodejs_compat flag (shown in the config above). This enables polyfills for common Node.js modules.

Environment variables

Don't use process.env in Workers. Instead, use SvelteKit's built-in $env modules:

// +page.server.js
import { SECRET_API_KEY } from '$env/static/private';

export async function load() {
    // Use SECRET_API_KEY here
}

For Cloudflare-specific bindings (KV, Durable Objects), access them via the platform object:

// hooks.js or +server.js
export async function handle({ event, resolve }) {
    const { env } = event.platform;
    // env.MY_KV_NAMESPACE, env.MY_DURABLE_OBJECT, etc.
    return resolve(event);
}

Worker size limits

The final Worker bundle must stay under Cloudflare's size limits (currently around 1MB gzipped). If your build fails with a size error:

Check for large dependencies bundled on the server side
Move heavy libraries to client-only imports if possible
Use dynamic imports for code splitting

Testing locally

You can test the production build locally with Wrangler:

pnpm build
wrangler dev .svelte-kit/cloudflare/_worker.js

This runs the exact same code that deploys to production, including platform bindings if you've configured them in wrangler.jsonc.

GitHub Actions for CI/CD

For automatic deployments on push:

# .github/workflows/deploy.yml
name: Deploy
on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: pnpm install
      - run: pnpm build
      - run: pnpx wrangler deploy
        env:
          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}

Create a Cloudflare API token with "Cloudflare Workers" edit permissions and add it as CLOUDFLARE_API_TOKEN in your repository secrets.

Why not Cloudflare Pages?

Both Workers and Pages can host SvelteKit, but there are differences:

Feature	Workers	Pages
Static assets	Via `assets` binding	Native
Serverless functions	Single `_worker.js`	`/functions` directory
Request limits	100k/day free	100k/day free
Build output	`.svelte-kit/cloudflare`	`.svelte-kit/cloudflare`

I prefer Workers because the adapter-cloudflare generates a single _worker.js file that handles routing, SSR, and static assets. It's simpler mentally. One entry point, one mental model.

Monitoring your usage

The Cloudflare dashboard shows your request volume and CPU time. Keep an eye on:

Requests: Free tier = 100k/day. At ~10k requests/day, you've got a 10-day buffer.
CPU time: SvelteKit usually runs under 5ms per request unless you're doing heavy computation.

If you're approaching limits, consider:

Prerendering more pages at build time
Caching API responses at the edge
Using KV for frequently-read, rarely-written data

Why I use this setup

Deploying SvelteKit to Cloudflare Workers gives you a production-grade hosting stack at zero cost. The edge runtime means faster response times for global visitors, and the free tier is genuinely usable, not just a teaser to get you hooked.

The setup is minimal: install an adapter, add a config file, run two commands. The rest is just SvelteKit doing what it does best.

SSH Config: From Spaghetti to Sanity

Asaduzzaman Pavel — Thu, 09 Apr 2026 22:33:19 +0000

For a long time, my "workflow" was just a series of Ctrl+R searches in my shell history, hoping to find that one specific IP address or long-forgotten identity file flag. It was "SSH Spaghetti." It worked, but it was friction-heavy.

I realized I needed a better way when our team moved behind a Bastion host (Jump Box). Suddenly, every time I wanted to check a log or run a quick query on an internal DB, I had to SSH into the Bastion, authenticate again, and then SSH into the internal server. It was exhausting. It broke my flow.

ProxyJump: making the infrastructure transparent

When I discovered ProxyJump, it felt like magic. I could define my Bastion and my internal servers once, and suddenly I was back to a single command: ssh internal-db. SSH handles the tunneling and identity forwarding behind the scenes.

Host bastion
  HostName 1.2.3.4
  User admin
  IdentityFile ~/.ssh/id_ed25519

Host internal-db
  HostName 10.0.1.50
  User postgres
  ProxyJump bastion

Instant connections with multiplexing

The second major shift was discovering multiplexing (via ControlMaster). I often have three terminal windows open for the same server: one for htop, one for logs, and one for a shell. I was used to the 2-3 second delay of the SSH handshake every time I opened a new tab.

Setting up connection reuse changed everything. The first connection took its usual time, but the second and third were instantaneous. It made the remote server feel like it was running locally.

The orphaned socket headache

...And then I realized that if the master connection hangs or the server reboots while I have multiple tabs open, the ControlPath socket gets orphaned. You'll try to SSH back in and get some cryptic error about the socket already being in use, or worse, it'll just hang indefinitely. I ended up having to write a tiny shell alias just to rm -rf ~/.ssh/sockets/* when things get weird. It's a trade-off I'm willing to make, but it's not the "fire and forget" solution people claim it is.

The IdentityFile trap

I once spent an hour debugging why I couldn't SSH into a new staging box. Turns out, because I had too many keys in my ssh-agent, the server was rejecting me for "Too many authentication failures" before it even got to the right key.

The fix is IdentitiesOnly yes. It tells SSH to only use the key specified for that host, rather than trying every key in your agent like a brute-force attacker. It's one of those things I think everyone should just have in their Host * defaults, but I'm not 100% sure if it breaks some edge cases with hardware tokens.

Keep-alives (a bit of a guess)

I use ServerAliveInterval 60 and ServerAliveCountMax 3, but honestly, those numbers are a total guess based on what seemed to work for my home office's flaky Wi-Fi. It stops those annoying "Broken Pipe" disconnects during my morning coffee breaks, but I've also seen it keep a "zombie" connection alive for 10 minutes after I've closed my laptop lid.

Host *
  ServerAliveInterval 60
  ServerAliveCountMax 3
  IdentitiesOnly yes
  ControlMaster auto
  ControlPath ~/.ssh/sockets/%r@%h:%p
  ControlPersist 10m

The real win here isn't saving a few seconds. It's removing the mental overhead of "getting there." Now, whether I'm jumping through a triple-bastion setup or just checking a dev box, the experience is identical. It's the "commute" of my workday, and I finally stopped dreading it.