DEV Community: Qasim Parray

PHP 8.5.12 RCE Patch: The Checklist I Run on Every Server

Qasim Parray — Sat, 24 Oct 2026 16:39:00 +0000

I was halfway through a coffee yesterday evening when the PHP security advisory landed in my feed, and the coffee did not survive the next ten minutes. Two critical remote code execution bugs, unauthenticated, and the PHP team's own wording was "update immediately". No "consider upgrading when convenient". That phrasing is rare enough that I stopped what I was doing.

Short version for the impatient: update to PHP 8.5.12, 8.4.27, 8.3.36 or 8.2.35, restart your workers, and confirm with php -v. Everything below is the checklist I'm using, the stopgap settings if you can't patch yet, and a few places where I think people will get tripped up.

I'm not a security researcher. I'm a developer who deploys PHP apps for clients and runs a few boxes of my own, so this is written from the "I have to patch this today and prove it" side of the fence. Read the primary sources too. I link them as I go.

What the advisory actually says

The official advisory on php.net names two bugs. The first is CVE-2026-109618, which the team describes as RCE via out-of-memory corruption. When PHP runs out of memory at a bad moment, it can be interrupted while internal request data is only half initialized, and the cleanup code then trusts that invalid data. The second is CVE-2026-109619, RCE via stale global state. Some request-owned internal state survives after its memory has been freed, and the next request on the same worker can pick it up before normal initialization resets it.

Both are unauthenticated. The team says the risk is highest for mod_php, where they have a demonstrated exploit that fires before any application code runs. That last part matters for how you think about this. Your framework's middleware, your WAF rules written against your routes, your login page: none of it is in the path. The bug lives below your code.

The affected list is wide. PHP-FPM, Apache with mod_php, php-cgi, FrankenPHP and LiteSpeed are all named. If your PHP serves web requests, you're in scope. Laravel News covered the release with the platform-by-platform status, which is the quickest way to see where Forge, Vapor, Cloud and Envoyer stand.

I'm deliberately not going to describe exploitation details. I don't know them beyond what the advisory says, and guessing would be worse than silence.

Which version you're on decides the next hour

Here's where I'd sort yourself, because the work is different for each bucket.

If you're on 8.2 through 8.5, the fix is a normal package or image update. The 8.5.12 changelog lists the fix for both advisories under Core as "Avoid state corruption via bailout", alongside a long pile of other fixes, including use-after-free bugs in DOM and BZ2 and a file descriptor leak in the built-in server. So even if the RCE bugs somehow didn't apply to you, this is not a release to skip.

If you're on 8.1 or older, the PHP project no longer ships updates for you. The security team published minimal source backports for 7.4, 8.0 and 8.1 for people building from source, which is generous, but I wouldn't treat it as a plan. If you have a distribution or LTS vendor, ask them for their backport. If you don't, this is the week the "we'll upgrade PHP next quarter" ticket becomes this week's ticket. I wrote about how I plan those upgrade windows in my Laravel 13 support window post, and the short version is that waiting for a security release to force the issue is the expensive way to do it.

If you use the volunteer-maintained Remi repo, read the notice carefully. Per Laravel News, it won't have updates today, and the PHP team recommends distribution packages or building from source in the meantime. That one catches people because "apt upgrade says nothing to do" feels like good news.

The checklist I'm using

Order matters here, so I'm keeping it boring and sequential.

First, find out what you actually run. Not what you think you run. On each server:

php -v
php-fpm8.4 -v 2>/dev/null
apachectl -M 2>/dev/null | grep -i php
ps aux | grep -E 'php-fpm|php-cgi|frankenphp|lsphp' | grep -v grep

The CLI version and the FPM version can differ, and I've been bitten by that before. A box can show a patched php -v while the FPM pool still runs the old binary because nobody restarted it. Which brings me to the second step: patching the package does not patch the running process. Workers that were started before the update keep running the old code until they restart.

sudo apt update && sudo apt install --only-upgrade php8.4-fpm php8.4-cli
sudo systemctl restart php8.4-fpm
# containers: pull the new base image, rebuild, redeploy
docker compose pull && docker compose up -d --build

Third, verify against the running thing, not the package manager. For FPM, I check the master process's binary and start time. For containers, I check the image digest of what's actually up.

php-fpm8.4 -v
systemctl show php8.4-fpm --property=ActiveEnterTimestamp
docker compose exec app php -v

Fourth, remember the platforms that don't patch you automatically. According to Laravel's status notes, Cloud was patched in place, but Forge servers need you to click Update PHP on each one, and Vapor needs a redeploy (a new deployment, not just a redeploy, if you're on a custom or Docker image runtime). Laravel also says Forge has no patch for PHP 8.0 or 8.1 and that Ubuntu 20.04 or older servers can't get the update at all. For those you need a new server on a supported Ubuntu release. I'd power the old box down until you've moved.

Fifth, patch Node too if the same box runs it. The Laravel News piece mentions Node.js security releases shipped alongside, and Forge doesn't update Node for you. I haven't read the Node advisory closely enough to say more, so go read it yourself.

If you can't patch today

The advisory has a section for this, and I'd read it on php.net rather than from my summary, because the details matter. The PHP team is blunt that these measures reduce exposure to specific attack paths and do not make an installation safe. Treat them as a seatbelt on the way to the update, not a substitute.

For the OOM bug, the advisory suggests setting memory_limit=-1 in a place applications can't override it, and a low post_max_size. The counterintuitive part is the unlimited memory limit. I'd have bet money the safer move was a tighter limit. The reasoning is that a finite PHP memory limit is a controllable way to trigger the out-of-memory failure, so removing it takes away the lever. They also say an underlying allocation failure can still reach the vulnerable path, so this is partial at best. And they warn against using RLIMIT_AS or RLIMIT_DATA as a substitute, because those can themselves cause the vulnerable allocation failure.

Here's what that looks like in an FPM pool, where php_admin_value can't be overridden by app code:

; /etc/php/8.4/fpm/pool.d/www.conf
php_admin_value[memory_limit] = -1
php_admin_value[post_max_size] = 8M
php_admin_value[upload_max_filesize] = 6M
php_admin_value[session.upload_progress.enabled] = 0

The 8M figure is the advisory's suggestion for apps without file uploads, and 32M for apps that need uploads, with upload_max_filesize kept below post_max_size. Adjust to your app.

For the stale global state bug, the advisory says to set session.upload_progress.enabled=0 and restart every worker, using php.ini, an FPM pool or server config that applies before request parsing. It specifically says not to rely on ini_set() or .user.ini, because they apply too late. There's also a PHP 8.5 item about fatal_error_backtraces=0. Read the full text, since I'm only summarizing part of it.

One thing I'd add from my own habits, and this is opinion rather than advisory: if unlimited memory makes you nervous on a small VPS, pair it with a cgroup or container memory limit that kills only the worker. The advisory itself recommends a container or cgroup limit as an availability boundary. On my own boxes that's a systemd drop-in with MemoryMax on the FPM unit, which I cover in my VPS hardening baseline.

What I'm still unsure about

I don't know yet how many installs are being probed. I haven't seen exploit traffic on my own servers, and absence of evidence on a handful of boxes means nothing. I also can't tell you whether the interim settings hold up, because the advisory itself hedges on them.

The other open question is logs. If an attacker got in before you patched, a clean php -v tells you nothing about the past. I'm checking web server access logs for oddly large or oddly shaped requests since the 21st and looking for unexpected files and processes under the web user. If you run anything with client data on it, assume you may want a proper incident review rather than my grep one-liners. For client work I'd rather write that email now than later.

Do these four things before you close the laptop

Check the PHP version on every server and container you own, then restart FPM or Apache and recheck against the running process. Move anything on PHP 8.1 or older onto a supported release, or get a written backport commitment from your vendor. If a box can't be patched tonight, apply the advisory's interim settings and put a calendar block on the patch. And if you maintain client sites, send each client a two-line note saying what you patched and when, because they will hear about this from somewhere else and it's better coming from you. If you want help with a patch sweep or the upgrade plan behind it, my work and contact details are at abrarqasim.com.

Originally published at abrarqasim.com. I write there about React, PHP, Rust, Go and the AI tooling around them.

TypeScript 7.1 Beta: Import Attributes in Ambient Modules

Qasim Parray — Fri, 23 Oct 2026 16:38:59 +0000

I have a file called globals.d.ts in more projects than I'd like to admit. It started life as three lines for *.css imports, and over time it picked up *.svg, *.md, *.txt and one cursed *.sql entry that I'm fairly sure nobody has touched since it was written. Every new repo, I copy it over without reading it. It works, so I never look at it.

Then I read the TypeScript 7.1 beta announcement and the first feature on the list made me open that file and wince. Ambient module declarations can now carry import attributes. That sounds like a tiny change. It isn't, because it quietly fixes a lie that wildcard declarations have been telling for years.

Short version for the impatient: if your project imports CSS, text or binary files, 7.1 lets you declare the type per import attribute instead of per file extension, and the compiler will complain when you forget the attribute. I haven't moved a client project onto the beta yet, so this post is a read of the announcement plus the checklist I'm going to run, not a victory lap.

The declaration file I keep copy-pasting

Here's roughly what lives in my globals.d.ts, and probably in yours:

declare module "*.css" {
  const content: CSSStyleSheet;
  export default content;
}

declare module "*.md" {
  const content: string;
  export default content;
}

declare module "*.txt" {
  const content: string;
  export default content;
}

Look at the second and third blocks. They are identical except for the extension. Every time I add a file type that should come in as a string, I paste another block. The declaration is keyed on the filename, but the thing that decides what you get at runtime is no longer the filename.

That's the part I had stopped thinking about. Import attributes, the with { type: "text" } bit after an import, exist because a runtime can't safely guess what a file is from its extension. The announcement uses the browser as the example: a .json file can't just be assumed to be JSON, so you say so in the import. The MDN reference for the with clause covers the JSON case, and the text, bytes and CSS variants are in the proposals the announcement links to.

So we have a runtime that dispatches on attributes and a type declaration that dispatches on extensions. They agree when everything goes well. They disagree the moment somebody forgets the attribute, and the old declaration still hands back a perfectly typed string for an import that will blow up at runtime or give you something else entirely.

What the 7.1 beta actually adds

The new syntax puts the attribute on the module declaration itself. This is straight from the announcement:

declare module "*" with { type: "css" } {
  const content: CSSStyleSheet;
  export default content;
}

declare module "*" with { type: "text" } {
  const content: string;
  export default content;
}

declare module "*" with { type: "bytes" } {
  const content: Uint8Array;
  export default content;
}

Three declarations replace my pile. The pattern is a bare *, and the type depends on the attribute. After that, a file import has to spell the attribute out:

import readme from "../README.md" with { type: "text" };   // string
import theme from "./theme.css" with { type: "css" };      // CSSStyleSheet
import photo from "./photo.png" with { type: "bytes" };    // Uint8Array

Drop the with clause and the import no longer matches any ambient declaration, so you get a compile error instead of a silently wrong type. That is the entire point. A forgotten attribute becomes something the compiler catches in your editor rather than something a user catches in the browser console.

Two details from the announcement are easy to skim past. First, imports matching these declarations are not checked against files on disk. If you typo the path, TypeScript won't tell you; your bundler or runtime will. That's the same as today's wildcard modules, but it's worth remembering that a * pattern means "anything goes" for the path half of the import.

Second, the team says these declarations are not shipped in the built-in libraries, and they recommend that libraries don't publish them either. You declare them in your own app. The reasoning is that lib.dom.d.ts and @types/node could each want to define their own, and a library that bakes one in will eventually collide with a built-in. I agree with that, and it also means my copy-the-file habit survives in a slightly smaller form. I'll still have a globals.d.ts. It will just be shorter and more honest.

Why the extension-keyed version was always slightly wrong

I want to be fair to the old pattern. For most apps, *.css plus a bundler config worked fine for years, and I'm not going to pretend it was a disaster. Where it falls over is when two environments disagree about a file type.

The announcement gives a concrete case. A bundler may treat .css imports as CSS Modules by default, handing you an object of class names. The browser's native behaviour with type: "css" is to hand you a CSSStyleSheet you can push into document.adoptedStyleSheets. Same extension, two different return types, selected by whether the attribute is present. A declaration keyed on *.css can only describe one of them. With the attribute in the declaration, you can have both: a CSS Modules declaration for plain .css imports and an attribute-qualified one for the stylesheet object.

I don't use that split often. Most of my sites take one approach and stick to it. But picture a project where a component library expects constructable stylesheets while the app shell uses CSS Modules. That's the setup where an extension-keyed declaration forces you to lie about one side. If that sounds like your codebase, this feature solves a real problem rather than a cosmetic one.

There's also the maintenance angle. With extension patterns, every new text-like format is another block. With attributes, a new .graphql or .sql file that should arrive as a string needs no new declaration at all, only the right with { type: "text" } at the import site. Fewer declarations means fewer places for a stale one to hide, and I have at least one stale one.

The part I'd check before trusting any of it

Beta software gets a checklist, not a leap of faith. This is the order I'm going to follow on a throwaway branch of a real project, not a toy repo.

Install it next to the stable compiler so I can compare: npm install -D typescript@beta. Then run the type check once on the old declarations to see that nothing changed. If the beta flags unrelated errors, that tells me whether any problems come from my config or from the release.

Next, replace the wildcard blocks with the three attribute-qualified ones and see what breaks. I expect a pile of errors on every import that lacks with. That list is the useful output. Each error is a place where the old setup was returning a type for an import that the runtime might treat differently.

Then check the tools around the compiler, because the compiler is the easy part. Does my bundler accept with { type: "text" } and emit the right thing? Does the test runner? Does the editor's language server pick up the new declaration form, or does it show red squiggles on valid code until it's updated? Vite, esbuild and Node each have their own timeline for text and bytes imports, and TypeScript accepting the syntax tells me nothing about whether my build does. I've been bitten before by a green type check on code that the bundler later refused, so this step gets the most time.

Finally, grep the repo for every declare module "*. line and write down which ones are for files that only one environment ever consumes. Those can stay as they are. Converting everything because I can would be the kind of tidy-up that creates a Friday-evening incident.

If your project has a declare module "*.svg" for React components via a bundler plugin, leave it alone. SVG-as-component is a bundler transform, not an import attribute, and the new syntax doesn't model it.

Source phase imports and the es2026 target

The beta has two more items I'd keep an eye on without rushing. Source phase imports add import source, which gives you a module as an inert, parsed-but-not-run object. For WebAssembly that object is a WebAssembly.Module, so you can write import source Fast from "./fast.wasm" and pass it straight to WebAssembly.instantiate. The announcement says Node already supports Wasm source imports in recent versions. For JavaScript files you can't do much with it yet, and many tools don't support it at all. Unless you load Wasm by hand, skip it for now.

The other is --target es2026 and --lib es2026 as stable options. The list in the announcement includes Array.fromAsync(), Error.isError(), Math.sumPrecise(), Uint8Array.fromBase64() and toHex(), plus getOrInsert() and getOrInsertComputed() on Map and WeakMap. That last pair is the one I'd use immediately. I've written the "get, check for undefined, set, return" dance on a Map more times than I can count, and a built-in replacement removes about four lines each time. Check your runtime's support before bumping the target, since the lib types only promise the declarations exist, not that your Node or browser version ships the methods.

If you read the TypeScript 7 changes with the Go-based compiler in mind, the new programmatic API entry points (typescript/sync, typescript/async and friends) matter for tool authors more than for app developers. I covered a related tooling shift in my post on Vite+ 1.0, oxlint and tsgolint, and the same rule applies here: measure on your own repo before changing anything.

What to do this week

Open your globals.d.ts and count the declare module "*. blocks that return the same type under different extensions. If that number is two or more, the attribute-qualified form will probably shrink your file. Install typescript@beta on a branch, swap those blocks, and read the error list before you decide anything. If you want to see how I approach this kind of upgrade on client work, my portfolio has the write-ups.

Originally published at abrarqasim.com. I write there about React, PHP, Rust, Go and the AI tooling around them.

Laravel DB::olap() on PlanetScale: When I'd Still Chunk

Qasim Parray — Thu, 22 Oct 2026 16:38:55 +0000

I read Paul Redmond's write-up of the new DB::olap() method on Laravel News this morning, and my first reaction was a mix of "nice, small, useful" and "I want to be suspicious of this before I trust it". I haven't run it against a PlanetScale branch yet. So everything below is a read of the article, the pull request and PlanetScale's docs, plus some opinions about where I'd get burned. Not a benchmark.

Short version for the impatient: DB::olap() is a tidy way to lift PlanetScale's per-query row cap for one callback. It is good for occasional exports and backfills. It is a bad default for anything a user is waiting on, and it has one trap that code review will miss.

What the limit actually is

PlanetScale runs MySQL on Vitess, and by default every query runs in an OLTP workload with guard rails. According to the PlanetScale system limits page, a query there can return, update or delete at most 100,000 rows, and a result set tops out at 64 MiB. Those numbers exist so one lazy report can't starve everyone else on the cluster.

The part that bites Laravel developers is not the limit itself. It's that nothing on your laptop enforces it. A local MySQL container happily returns two million rows, your export job passes its test with a seeded table of fifty rows, and the first time it meets a real customer with three years of orders it falls over in production. The code is identical. The database is not.

That's an old category of bug, and I've never found a cure other than running against something shaped like production. I wrote about a different flavour of the same problem, indexes your tests never notice are missing, and the lesson there applies here: a green test suite on a small database proves very little about a big one.

Vitess has a second workload, OLAP, that drops those limits. Until now, using it from Laravel meant reaching for a raw statement.

The old way and the new way

Before Laravel 13.36, running one query in OLAP mode looked like this:

try {
    DB::statement("set workload = 'olap'");

    $rows = Order::query()
        ->where('created_at', '>=', now()->subYears(3))
        ->get();
} finally {
    DB::statement("set workload = 'oltp'");
}

Two things are wrong with that, and the article spells both out. The raw statement runs on the write connection, so if you have read replicas the select goes to a read connection that never left OLTP mode. You set the flag and the query ignored it. And because the workload is a session setting, a missing finally leaves the connection in OLAP for whatever runs next, which in a queue worker or an Octane process is somebody else's job.

The new method, added in this framework pull request, wraps all of that:

$revenue = DB::olap(fn () => Order::query()
    ->selectRaw("customer_id, date_format(created_at, '%Y-%m') as month, sum(total) as revenue")
    ->where('created_at', '>=', now()->subYears(3))
    ->groupBy('customer_id', 'month')
    ->get()
);

It sets the workload on both the write and the read connection, runs your callback, and flips back to OLTP in a finally block. Whatever the callback returns, you get back. If the database isn't Vitess, it just calls the callback and does nothing, which means the same code runs on local MySQL and in CI without a branch.

I like that last decision a lot. A helper that only works against one vendor would force an if at every call site, and people would forget it. A no-op elsewhere is the right default.

One catch: the method lives on the MySQL connection class. If your default connection is PostgreSQL or SQLite, DB::olap() throws a BadMethodCallException. That matters if you run SQLite in tests and MySQL in production. You'd get a failure in the one place you didn't want one.

The trap: lazy results leave the callback

This is the part I'd flag in every pull request that uses the method.

The workload flips back the moment the callback returns. So this looks right and isn't:

$orders = DB::olap(fn () => Order::query()->cursor());

foreach ($orders as $order) {
    // the query actually runs here, back in OLTP mode
}

cursor(), lazy() and lazyById() return a LazyCollection, and a lazy collection doesn't touch the database until something iterates it. The arrow function returns the collection, olap() resets the workload, and then your foreach triggers the real query under the old limits. The code reads as correct. It fails, or worse, silently runs under different rules than you think.

The fix is boring: iterate inside the callback, or call get() there. The article's queued export does the first. But "boring fix" and "easy to notice in review" are different things. An arrow function returning a query builder chain looks identical whether the last call is get() or cursor().

There's a second, quieter limit. OLAP removes PlanetScale's 64 MiB result cap, but it doesn't remove PHP's memory_limit. A get() over three years of orders moves the ceiling from the database to your worker's memory. I'd pair olap() with lazyById() and a loop that writes rows out as it goes, and I'd treat a bare get() over a big table as a smell even when the database allows it.

Where I would still chunk

PlanetScale's own docs recommend against OLAP for regular application queries. The article summarises that guidance: the OLTP limits stop long-running queries from using up the database's resources, and large reads are better paginated or copied to a separate analytics database. It also says OLAP queries can fail if the connection to PlanetScale is interrupted.

That last point changes how I'd write an export. Suppose a queued job streams a million rows inside one olap() call and the connection drops at row 900,000. The job retries, and it starts over from row one. For a nightly report nobody is waiting on, that may be fine. For anything with a deadline, I'd rather have a job that remembers where it stopped:

public function handle(): void
{
    $lastId = Cache::get("export:{$this->path}:last_id", 0);

    Order::query()
        ->where('id', '>', $lastId)
        ->chunkById(5000, function ($orders) {
            $this->append($orders);
            Cache::put("export:{$this->path}:last_id", $orders->last()->id, now()->addDay());
        });
}

That runs entirely in OLTP mode, each chunk is a small query well under every limit, and a retry picks up near where it died. It's more code than DB::olap(). It's also the version I'd bet on at 2am.

My rough rule: reach for olap() when the job is one-off or rare and a restart is cheap. A backfill, an admin report, a data fix. Reach for chunking when the work is recurring, user-facing, or expensive to repeat. And for reporting that keeps growing, stop reading the production database at all and copy the data somewhere built for it, which is exactly what PlanetScale suggests.

The article frames olap() around reads, and I'd keep it there. I haven't seen anything that tells me the OLAP workload is a good idea for the update and delete side of that 100,000-row limit, so for bulk writes I'd still chunk and not assume.

A guard I'd put around it

Because the method is so easy to call, I'd wrap it once and make the dangerous uses harder. Something like:

final class HeavyRead
{
    public static function run(Closure $callback): mixed
    {
        if (! app()->runningInConsole()) {
            throw new LogicException('Heavy reads belong in queued jobs or commands.');
        }

        $start = microtime(true);

        try {
            return DB::olap($callback);
        } finally {
            Log::info('heavy read finished', [
                'seconds' => round(microtime(true) - $start, 1),
            ]);
        }
    }
}

It refuses to run inside a web request, so nobody wires a "download all orders" button straight to an unlimited query. It logs a duration, so you notice when a one-off report quietly becomes a nightly habit. And with the one call site in one file, reviewing for the lazy-collection mistake is a single grep.

Two smaller details from the article are worth knowing. The same pull request adds isVitess() to the MySQL connection, which returns true when the server's version string mentions Vitess or PlanetScale. Like isMaria(), it connects to the database to read that version, so the first call costs a round trip. And if your read connection hasn't connected yet when you call olap(), the method connects it first. Neither is a problem. Both are the kind of thing I'd want to know before I saw an unexpected connection in a profiler.

What I would do this week

Search your codebase for exports, reports and backfills that call get() or all() on a table that has grown. Those are your candidates, and they're also the jobs most likely to have never been run against production-sized data.

Then pick one and test it against a PlanetScale development branch with a realistic row count, not a seeded fifty. If it fails on the limit, you have two honest options: wrap it in DB::olap() with iteration inside the callback, or rewrite it with chunkById() so a retry resumes. Decide per job using the restart-cost rule above.

Last, grep for set workload in your repository. Any raw statement you find is a replica-routing bug or a leaked session waiting to happen, and swapping it for DB::olap() is a five-minute change.

If you're running Laravel on PlanetScale and want a second pair of eyes on an export that keeps timing out, that's the kind of backend work I do. You can see more of it on my portfolio.

Originally published at abrarqasim.com. I write there about React, PHP, Rust, Go and the AI tooling around them.

Retainer Agreement Template for Web Developers: Clauses That Matter

Qasim Parray — Thu, 22 Oct 2026 08:38:55 +0000

Picture the lazy version of a retainer. A developer writes it on one line in an email: "Ten hours a month, same rate, invoiced on the first." The client says yes within the hour, and everyone feels very professional for roughly three weeks. Then a request lands on day 29 that is really a small project, the client asks what happens to unused hours, and someone wonders whether "ten hours" includes the time spent reading emails.

None of that was in the one-liner. That's the job a retainer agreement does, and a one-liner doesn't do it. Below is the template I'd use today for a web developer retainer, the reasoning behind each clause, and the places where I think most templates online quietly fail the developer.

I'm not a lawyer, and this isn't legal advice. Treat the wording as a starting point and get a local professional to read it before you attach your name to it, especially if your client is in another country.

Decide what the client is buying

A retainer can sell three different things, and the agreement should say which one you mean.

The first is a bank of hours. The client gets a fixed number of hours each month at an agreed rate. This is the easiest to explain and the easiest to argue about, because every hour becomes a unit someone can question.

The second is availability. The client pays for the right to reach you within a stated response time, whether or not they use it. This is closer to an insurance premium, and it suits maintenance work for a site that mostly runs by itself.

The third is a defined outcome: for instance, "keep the site patched, backed up and monitored, and fix anything that breaks within one business day". You're selling the result and you absorb the variance in hours.

I lean toward the third for small sites and the first for active product work. The mistake is mixing them without saying so. If the agreement promises a one-day response time and also caps you at ten hours, you've written a contract that you'll break in the first busy month, and the client has no idea.

If you haven't already talked through scope with the client, do that before you send anything. My list of discovery call questions is what I'd run through first, because half of these clauses get easier to write once you know what the site actually does.

The clauses that matter

Here is the skeleton. Short on purpose.

RETAINER AGREEMENT

1. Services. The Developer will provide the services listed in Schedule A
   (maintenance, updates, monitoring, and small changes) for the Client's
   website at [domain].

2. Monthly fee. The Client will pay [amount] per month, invoiced on the
   [first] of each month, payable within [14] days.

3. Included time. The fee covers up to [N] hours per month. Time is tracked
   in 15-minute increments and reported monthly.

4. Unused time. Unused hours [expire at month end / roll over for one month].

5. Extra work. Work beyond Schedule A or beyond [N] hours is quoted
   separately and does not start until the Client approves the quote in writing.

6. Response times. The Developer will acknowledge requests within [1]
   business day. Emergency means the site is down or taking payments
   incorrectly; those requests are handled first.

7. Term and ending. This agreement runs month to month. Either party can end
   it with [30] days written notice.

8. Ownership. The Client owns the work product once the month's invoice is paid.
   The Developer keeps rights to general tools and code not specific to the Client.

9. Liability. The Developer's liability is limited to the fees paid in the
   preceding [3] months.

Most of that is boilerplate. A few clauses carry all the weight, and those are the ones I'd spend an evening on.

Unused hours

Clause 4 is where the money argument happens. If hours expire, the client feels cheated in quiet months and the developer feels fine. If hours roll over without limit, you can end up owing someone 60 hours at the worst possible moment. I'd pick expiry as the default, and offer a single month of rollover if the client pushes. Whatever you choose, write it down. An unstated rollover rule means the client will assume the generous version.

What counts as extra

Clause 5 is the one the day-29 request breaks. Define "small change" with a number, not an adjective. Something like "any single request that I estimate at more than three hours is a project and gets its own quote". Then the client doesn't have to argue with your opinion of what "small" means. They can argue with an estimate, which is a much more productive fight.

Approval in writing matters because it protects both sides. An email reply is fine. A verbal "yeah go ahead" on a call is how a retainer becomes unpaid project work.

Ending it

Month to month with notice is boring and it's the right answer for most small clients. Long fixed terms scare people off, and a client who can't leave tends to become a client who resents you. A 30-day notice period gives you time to hand over credentials and documentation, and it gives them time to find someone else without a gap in coverage.

Billing it so it actually gets paid

A retainer that depends on you remembering to send an invoice on the first of the month will fail in the month you're busiest, which is also the month the client most needs the cash flow to be dull and predictable.

If your clients can pay by card, a recurring subscription takes the chasing out of it. Stripe documents the model in its subscriptions overview: you create a price, attach the customer, and the billing happens on a schedule without you. For clients who need a proper invoice with a PO number or bank transfer details, Stripe Invoicing can generate and send those on a schedule too. Neither is the only option, and I don't have a stake in the choice. The point is to remove yourself from the loop.

Two things I'd add. First, send the hours report with the invoice, even when the client never asks for it. A short list of what you did builds trust faster than any promise about quality. Second, decide in advance what happens when a payment fails. A sensible default is a reminder at day 7, a pause on non-emergency work at day 14, and a conversation by phone before anything harsher. Write that sequence into clause 2 or a short schedule so it isn't a personal decision at the worst moment.

Where templates online get it wrong

Free retainer templates tend to share the same weaknesses.

Many are written for consultants or agencies and talk about "deliverables" and "milestones" in a way that doesn't fit ongoing maintenance. A retainer is a service relationship, not a project with an end date.

Many bury the response time or skip it. Clients buy retainers because they want to know that someone will pick up the phone. If the agreement doesn't say how fast, the client will fill in "immediately" in their head.

And some give the developer almost no protection on scope. A line like "ongoing website support" is an invitation. Schedule A should list what is included in plain words, such as plugin and framework updates, uptime monitoring, nightly backups with a monthly restore test, and small content or layout edits. It should also list what is excluded: new features, redesigns, third-party integrations, and anything caused by changes someone else made to the server.

The Freelancers Union publishes free resources on contracts and getting paid, and it's worth a read if you're newer to this. If you want my view on the broader contract, I wrote up six questions I ask before I sign, and most of them apply here too.

What I'd do this week

Open the last retainer proposal you sent, or the email where you described one, and check it against the skeleton above. Find the three clauses it's missing. For most people that's unused hours, the definition of extra work, and the notice period.

Then write Schedule A as two short lists, included and excluded, and send the updated version to your next client before they ask. If you already have clients on a retainer with no written agreement, send them the new one with a short note and offer to talk it through. Nobody has ever been upset to be asked what happens to the unused hours before the answer matters.

If you'd like to see how I scope and price this sort of work, my portfolio is the place to start.

Originally published at abrarqasim.com. I write there about React, PHP, Rust, Go and the AI tooling around them.

Rust vs C++: Who Checks the Lifetime, and When

Qasim Parray — Wed, 21 Oct 2026 16:38:53 +0000

Short version for the impatient: the real difference between Rust and C++ is not speed. Both compile to native code and both can hit the same hardware limits. The difference is who checks your lifetimes, and when. C++ lets you check them yourself, with discipline and tooling. Rust makes the compiler check them before the program exists.

I want to show that with a small program rather than a slogan, because I've read a lot of "Rust vs C++" posts that are just two benchmark charts and a fan club. I write mostly PHP, Go and TypeScript for clients, so I'm not a systems programmer, and I won't pretend to have shipped a game engine in either language. What I can do is take a mistake that every C++ beginner makes, run it on a real machine, and compare it to what Rust does with the same idea.

The bug that compiles

Here is a C++ program that moves a string out of a smart pointer and then reads from the pointer anyway.

#include <iostream>
#include <memory>
#include <string>

int main() {
    auto name = std::make_unique<std::string>("report.pdf");
    auto other = std::move(name);
    std::cout << *name << "\n";
}

I built this with g++ -Wall -Wextra on a Linux box. No warnings. No errors. It ran and died with a segmentation fault (exit code 139). The move constructor did exactly what it promises: name is now an empty pointer, and dereferencing an empty pointer is undefined behaviour. The compiler knew that std::move had just been called on name. It let me carry on anyway, because the language says a moved-from object is valid but unspecified, and the language leaves it to me to remember.

That's not a knock on C++. A segfault in a toy program is the good outcome. The bad outcome is the same mistake inside a request handler where the pointer isn't null but points at memory something else now owns. Nothing crashes. Something gets quietly overwritten.

Now the same idea in Rust:

fn main() {
    let name = String::from("report.pdf");
    let other = name;
    println!("{name} {other}");
}

This does not build. The compiler stops with error E0382, "borrow of moved value", and points at the line where name was moved and the line where I used it afterwards. There is no runtime to crash, because there is no executable. The Rust Book chapter on ownership states the rules in three lines: each value has an owner, there is one owner at a time, and when the owner goes out of scope the value is dropped. The move bug above is simply the second rule being enforced.

Ownership is a rule, not a convention

C++ has all the same ideas. Smart pointers, RAII and move semantics are the C++ answer to manual memory management, and modern C++ written with them is far safer than the C-with-classes code that gave the language its reputation. The C++ Core Guidelines are full of advice in exactly this direction: prefer unique_ptr, avoid raw owning pointers, don't hold references past the lifetime of the thing they point at.

So if both languages have the idea, what's the difference? Enforcement. In C++ the guidelines are guidelines. A tool such as clang-tidy or a static analyser can flag many violations, and a code reviewer can catch more, but the language itself accepts the program. In Rust the same rules are part of the type system, and a program that breaks them is not a valid Rust program.

I find it useful to think of it as the difference between a speed limit sign and a speed bump. Most drivers slow down for both. Only one of them works at 3am when you're tired.

There's a cost, and I'll get to it. First, the second kind of bug, because it is the one that actually worries me.

Dangling references and the lifetime annotation

Returning a reference to something that no longer exists is the classic. In C++ it looks harmless:

const std::string& longer(const std::string& a, const std::string& b) {
    return a.size() >= b.size() ? a : b;
}

int main() {
    const std::string& r = longer("a long literal", std::string("hi"));
    std::cout << r << "\n";
}

The temporary std::string("hi") is destroyed at the end of the full expression. If it happened to be the longer one, r would now refer to a dead object. Here the literal wins, so this particular run probably prints correctly, which is the whole problem: it works until the inputs change. I'm describing that behaviour from the language rules, I didn't run this one to see what my compiler does with it.

Rust forces you to say how long each reference lives:

fn longest<'a>(a: &'a str, b: &'a str) -> &'a str {
    if a.len() >= b.len() { a } else { b }
}

fn main() {
    let result;
    {
        let short = String::from("hi");
        result = longest("longer text", &short);
    }
    println!("{result}");
}

The 'a says that the result lives no longer than the shorter of the two inputs. Because short is dropped at the closing brace and result is used after it, the compiler rejects the program with E0597, "short does not live long enough". The function is correct. The caller is wrong, and Rust tells the caller.

Those annotations are the most disliked part of the language, and I get why. They look like noise until you've been bitten by the thing they prevent. The Rustonomicon is blunt about where the boundary sits: in safe Rust the compiler guarantees the absence of this class of bug, and in unsafe blocks the guarantee becomes your job again. That is a much smaller area to audit than "the whole codebase".

What Rust costs you

I'd be doing the thing I complained about at the top if I stopped here. Rust costs real time.

The borrow checker will reject programs that are fine. Graph structures, doubly linked lists and anything with cyclic references fight the ownership model, and the usual escape hatches (Rc<RefCell<T>>, indices into a Vec, unsafe) each give up something. When I read Rust written by people who are new to it, the pattern I see most is .clone() sprinkled on until the errors go away. That works, and it quietly spends the performance you chose Rust to keep.

Compile times are slower than I'd like. The ecosystem is younger, so a library you take for granted in C++ for audio, CAD or an old hardware vendor's SDK may not exist, or may be a thin wrapper over the C++ one anyway. And if you have a decade of C++ in production, rewriting it is a business decision, not a technical one. I covered a smaller version of that trade in my post on Rust 1.99 and the box leak habit I had to drop, where even a language that polices ownership still lets you leak memory on purpose if you ask.

C++ has costs too, and they're mostly invisible until they aren't. The language is huge, with decades of overlapping ways to do one thing. Two engineers on the same team can write "modern C++" that looks like two different languages. Undefined behaviour doesn't announce itself.

How I'd choose

I'd pick C++ when the code has to live next to an existing C++ codebase, when a library only exists there, or when the team already has people who know where the bodies are buried. Rewriting a working system to get memory safety is rarely worth it by itself, and incremental approaches that put new code in Rust next to the old code are usually kinder to the schedule.

I'd pick Rust for new code that handles untrusted input, runs for a long time, or gets maintained by people who weren't in the room when it was written. Parsers, network services, command-line tools and anything that sits between the internet and a database are good fits. The ownership rules double as documentation. When a function takes String instead of &str, that signature tells the next developer who is responsible for the memory.

For the kind of work I do for clients, neither is the default. A Laravel app or a Go service covers most of what people hire me for, and I reach for a systems language only when a hot path justifies it. You can see what that mix looks like on my portfolio.

Try it yourself this week

Don't take my word, or any benchmark's word, for any of this. Spend an hour on it:

Write the unique_ptr move bug above in C++ and compile it with -Wall -Wextra. Then compile the same file with -fsanitize=address,undefined and run it. See what each tool tells you.
Install Rust with rustup and write the longest function with the nested block. Read the full E0597 message, not just the first line. Then delete the 'a annotations and read the different error you get.
Pick one small function from your own C++ code that returns a reference or a pointer. Write down, in a comment, who owns the thing it points at. If you can't answer in one sentence, you've found the kind of bug Rust is built to catch.

If step three turns up a real question, that is a better reason to learn Rust than anything I've written here.

Originally published at abrarqasim.com. I write there about React, PHP, Rust, Go and the AI tooling around them.

Discovery Call Questions I Ask Every Web Client Before Quoting

Qasim Parray — Sun, 18 Oct 2026 08:38:46 +0000

My worst quote ever was for a "simple brochure site." I priced it in ten minutes after a friendly twenty-minute call, and the client was lovely. Three weeks in, I learned that "brochure" included a members area, an Arabic and English version, and an import of 900 products from a spreadsheet nobody had opened since 2019. I did the work. I also earned roughly the hourly rate of a part-time barista.

Nothing was wrong with the client. The call was wrong. I asked what they wanted and wrote down the answer, which is a different thing from finding out what they needed. Since then I've kept a short list of discovery call questions, and I skip none of them, even when a lead is charming and in a hurry. Especially then.

This post is that list, with the reason behind each question and the answer that makes me slow down. It's built for freelance web projects, but most of it works for any small agency job.

Ask about the problem before the website

"What do you want built?" gets you a feature list. The feature list is usually a guess at a solution to a problem you haven't heard yet. So I open with a different question: what happened that made you decide to do this now?

Something always happened. A competitor launched a new site, a developer left, the old site got hacked, a campaign needs a landing page by March. The trigger tells you the real deadline and the real stakes, and it tells you who is nervous. A site rebuild triggered by "our agent quit and the site is down" is a very different job from one triggered by "we feel dated."

Rob Fitzpatrick's The Mom Test is a book about customer interviews for startups, but its core idea transfers cleanly: ask about specific past events instead of hypothetical futures. Nobody can reliably tell you whether they'd use a feature. They can tell you what they did last Tuesday when the old system failed. I now ask "walk me through the last time a customer tried to book something on your current site" and I take notes like a court reporter.

Two follow-ups I always add. What does success look like in six months, in numbers if possible? And what would make you call this project a failure? The second one is the better question. People answer it fast, and the answers are specific.

Find out who decides and who pays

I've been burned by the sponsor who loves my proposal and then needs "sign-off from the partners." So early in the call I ask who else will have an opinion about this project, and who signs the invoice.

If the answer is a committee, I ask to meet the loudest member, or at least to get their written requirements before I quote. A decision-maker I never meet is a stakeholder who will appear at the end with a list of changes. That connects directly to scope, which I covered in how I handle scope creep. Most scope creep I've dealt with was an undiscovered stakeholder in disguise.

The budget question makes freelancers squirm, so here's the phrasing I use: "Projects like this usually land somewhere between X and Y depending on the answers to what we're discussing. Does that range sit in the same world as what you had in mind?" It's not a trick. It saves us both a week of proposal writing if the number is a different order of magnitude from their expectation. The answer I dislike most is "we don't have a budget in mind." That usually means they've never bought this before, and I need to spend more of the call explaining what good work costs. I wrote about how I arrive at those ranges in how I actually price freelance web development work.

Ask what already exists

This is the section where my brochure-site quote fell apart. Before any quoting, I want an inventory of what is already out there, and I ask it as plainly as that.

What is the current site built on? Who has the hosting login and the domain registrar login? Is there content to migrate, and how much of it is real versus abandoned? Are there integrations: payments, a CRM, a booking tool, a newsletter list? Is there analytics, and does anyone read it?

Migration deserves its own paragraph because it is where hours vanish. If the URLs are changing, someone has to map old addresses to new ones and set up redirects, or the client's search traffic quietly dies. Google's guide to site moves with URL changes is the document I send people who think a redesign is only a visual job. I ask for a crawl or a sitemap export on the call, and I get a rough page count before I say a price out loud. "About 40 pages" and "about 900 URLs" are not the same project, and clients are often honestly unaware of which one they have.

Domain access is the unglamorous question that has stalled more launches than any technical problem. If the registrar account belongs to a former employee's personal email, I want to know in week one, not launch day.

Constraints nobody mentions unless you ask

Some requirements are invisible until they're violated. I ask about them directly, because the client assumes they're obvious.

Languages and right-to-left layouts, for one. Accessibility, for another: if the client is a government body, a school or a larger company, there may be a legal or contractual standard, and the W3C Web Accessibility Initiative's planning guidance is a good reference for the conversation. Retrofitting accessibility at the end costs far more than designing for it from the start, so I'd rather know now.

Then there's who maintains the site after launch. If the answer is "the marketing intern, in WordPress," that shapes my technology choices more than anything else on this list. I once proposed a lovely headless setup to a client whose only technical person was an office manager. It was the wrong tool for them and I knew it halfway through the call, but I had already started getting excited. Now I ask the maintenance question early enough that it can veto my enthusiasm.

Other quick ones: any hard launch date and what it's tied to, any brand guidelines or a designer already involved, any legal copy (privacy policy, cookie consent) they need, and whether they have photos or I should budget for stock. Each takes thirty seconds to ask and has cost me a day when I didn't.

Close the call with a promise you can keep

At the end I repeat back what I heard in about five sentences, and I say when they'll get a written proposal. Then I do exactly that. The recap catches misunderstandings while they're cheap to fix, and clients often correct one detail in a way that changes the quote.

I also tell them what I will need from them: a named decision-maker, access to current accounts, and any existing content. Setting that expectation before the contract keeps "waiting on the client" from becoming my fault in a timeline conversation later. When the call went well, the proposal nearly writes itself, and I've shared the structure I use in my web development proposal template.

Not every lead should get a proposal, and discovery is also where I find that out. A client who refuses to say who decides, won't discuss budget and wants a fixed price by Friday is giving me information. Sometimes the best output of a discovery call is a polite no.

Try it on your next call

You don't need the whole list. Pick the three questions you've been skipping because they feel awkward, probably the budget one and the "who else decides" one, and write them at the top of your call notes before your next lead. Ask them in the first fifteen minutes, when it feels slightly rude, instead of the last five, when it feels like an interrogation.

After the call, compare what you learned with what you would have quoted from a form submission. If the gap is large, you've found your own version of my brochure site. This is the filter I use for the projects that come through my freelance practice, and it has saved me from more bad fits than any contract clause.

Originally published at abrarqasim.com. I write there about React, PHP, Rust, Go and the AI tooling around them.

Linux Server Hardening on a Small VPS: The Baseline I Run First

Qasim Parray — Sat, 17 Oct 2026 16:38:44 +0000

I once locked myself out of a client's server at 11pm because I reloaded sshd with a typo in the config and closed my only terminal. The fix involved a rescue console, a cold coffee and a long apology. That night taught me more about linux server hardening than any checklist had, and it is why the first rule in this post is about what to do before you change anything.

Short version for the impatient: on a fresh small VPS I do five things. Key-only SSH, no root login, a deny-by-default firewall, fail2ban for the noise, and automatic security updates. That takes about ten minutes, and it removes nearly everything that actually gets small servers owned. If you want the reasoning and the config, keep reading.

I run client apps on cheap VPS boxes, mostly Ubuntu 24.04, and I'm not a security specialist. This is a baseline for a server that hosts a web app, a database and a few containers. It is not a compliance program. If you need CIS-level hardening, the CIS Ubuntu benchmark is the document to start with, and it is much longer than what follows.

Open a second terminal before you touch sshd

Here is the habit that would have saved my night. Log in twice. Keep the second session idle and never close it until you have proven that a brand new connection works. A running SSH session survives an sshd reload, so the idle one is your way back in.

Then validate before you reload. sshd -t parses the config and prints errors without touching the running daemon. It costs one second. I skipped it exactly once.

sudo sshd -t && sudo systemctl reload ssh

If that command prints nothing and returns, the config is syntactically fine. It does not tell you the config is what you meant, which is why the second terminal stays open and you test a fresh login from a third window.

SSH: keys only, no root, short leash

Most of the hardening value lives here, because SSH is the one door every VPS has open to the whole internet from minute one. Watch /var/log/auth.log on a new box for ten minutes and you will see strangers trying admin, ubuntu and root with passwords from a list.

I put my changes in a drop-in file instead of editing the main config. On Ubuntu, /etc/ssh/sshd_config includes everything in /etc/ssh/sshd_config.d/*.conf, and sshd uses the first value it finds for each setting. So the filename matters. Cloud images often ship a file like 50-cloud-init.conf that sets PasswordAuthentication yes, and because the first value wins, a file that sorts after it loses. I name mine 01-hardening.conf so it is read first, and then I check the effective result instead of trusting my eyes.

# /etc/ssh/sshd_config.d/01-hardening.conf
PasswordAuthentication no
KbdInteractiveAuthentication no
PermitRootLogin no
MaxAuthTries 3
LoginGraceTime 20
AllowUsers deploy

My first attempt used a 99 prefix and silently lost to the cloud-init file. So after every change I run sudo sshd -T | grep -Ei 'passwordauth|permitroot|maxauth', which prints the settings sshd will actually use. I got this wrong for a while by reading the files instead of asking the daemon, and the daemon disagreed with me twice.

A few notes on those lines, all checked against the sshd_config man page. PermitRootLogin already defaults to prohibit-password, so root can't log in with a password out of the box, but setting it to no removes the question entirely. MaxAuthTries defaults to 6, and I drop it to 3 because I authenticate with a key and never need six attempts. KbdInteractiveAuthentication no matters because with PAM enabled, keyboard-interactive can sneak password logins back in even when PasswordAuthentication is off.

AllowUsers deploy is the line people skip and I think it deserves more credit. Every account that isn't named there is refused no matter what else is true. Add a new service account later and forget about it, and it still can't log in over SSH.

One caveat on moving SSH to another port. I used to do it. It cuts log noise a lot and stops nothing, since a scanner finds port 2222 in seconds. If your logs are loud, fail2ban handles that better and doesn't break every tool that assumes port 22.

A firewall that denies by default

SSH is not the only thing listening. A fresh image may have a database, a forgotten Redis, a metrics agent or a dev server bound to all interfaces, and you may not remember starting it. A host firewall makes the answer to "what is exposed" a short list you wrote yourself.

On Ubuntu that's ufw, which ships with the system. The order of commands matters, because enabling a deny-by-default firewall before allowing SSH is another way to lock yourself out.

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw limit OpenSSH
sudo ufw allow 80,443/tcp
sudo ufw enable
sudo ufw status verbose

ufw limit is allow plus a rate limit: it throttles an address that opens too many connections in a short window. It's not a replacement for fail2ban, but it's free and one word.

Now the part that bit me. If you run Docker, ufw does not protect your published container ports the way you would assume. Docker writes its own rules into the firewall, and traffic to a published port is diverted before it ever reaches the rules ufw manages. So -p 5432:5432 on a database container can be open to the internet while ufw status swears everything is closed. The Docker documentation on ufw says the two are incompatible in this way and describes the options.

My rule is dull and effective. Publish ports on loopback only (-p 127.0.0.1:5432:5432) unless something truly needs the public interface, and put a reverse proxy in front for the rest. For client sites I went one step further and stopped opening inbound ports at all, which I wrote up in my Cloudflare Tunnel post. If a port isn't open, there's nothing to firewall.

After enabling, verify from outside. Run nmap against your own IP from another machine, or use an online port scanner. Looking at the firewall from the inside only tells you what you configured.

Fail2ban for the noise, not for safety

Fail2ban reads logs, spots repeated failed logins and bans the source address in the firewall for a while. I install it on every box, and I try to be honest about what it does. The project's own README says it reduces the rate of incorrect authentication attempts but cannot eliminate the risk of weak authentication. With key-only SSH, brute force can't succeed anyway. What fail2ban buys me is quieter logs and less wasted CPU, which also makes real anomalies easier to spot.

The defaults in the upstream jail.conf are a ban time of 10 minutes, a find window of 10 minutes and 5 retries. The sshd jail on Ubuntu is enabled by the packaged defaults, but I still write a small local override instead of editing jail.conf, because package upgrades can overwrite the latter.

# /etc/fail2ban/jail.d/local.conf
[DEFAULT]
bantime  = 1h
findtime = 10m
maxretry = 4

[sshd]
enabled = true

Then sudo systemctl restart fail2ban and sudo fail2ban-client status sshd to see current bans. If you have a fixed IP, put it in the ignoreip setting so a few fat-fingered logins from your own desk can't ban you.

Automatic security updates and the leftovers

Unpatched software is the dull way servers get breached, far more often than anything exotic. Ubuntu's unattended-upgrades installs security updates on its own, and the Ubuntu Server documentation on automatic updates covers the setup. On most images it's already installed. Check with systemctl status unattended-upgrades and look at /var/log/unattended-upgrades/ to confirm it actually ran.

Two things I decide deliberately. First, automatic reboots: the kernel updates need a reboot to take effect, and I enable Unattended-Upgrade::Automatic-Reboot with a 04:00 reboot time only on boxes where a minute of downtime doesn't matter. On client production servers I leave reboots manual and put it on a monthly calendar reminder. Second, the update scope. The default is security updates only, and I keep it that way. A surprise major-version bump of Postgres at 3am is not a security fix.

Smaller leftovers that take a minute each:

Remove packages and services you don't use. ss -tlnp shows what is listening and which process owns it.
Create a non-root user with sudo, and give it a key before you disable anything.
Keep /etc/ssh/sshd_config.d/01-hardening.conf and the fail2ban override in version control so the next server is a copy and paste.
Take a backup before you start. I use restic, and my restic backup setup for a small VPS covers the retention and the restore test I keep forgetting to do.

Your next ten minutes

Pick one server you run today, probably the one you set up fastest and have looked at least since. Open a second SSH session first. Then run sudo sshd -T | grep -Ei 'passwordauth|permitroot|maxauth|allowusers' and read what the daemon says, not what you remember. If password authentication is still on, fix that before anything else in this post.

After that, run sudo ufw status verbose and ss -tlnp side by side. Every listening port with no matching reason to be public is your homework for this week. I do this kind of review on client infrastructure as part of my freelance work, and the list it produces is almost always shorter than people fear and more embarrassing than they expect.

Originally published at abrarqasim.com. I write there about React, PHP, Rust, Go and the AI tooling around them.

Postgres Materialized View Auto Refresh with pg_ivm 1.16

Qasim Parray — Sat, 17 Oct 2026 08:38:44 +0000

Okay, confession: for a long time my answer to "the dashboard is stale" was a cron job that ran REFRESH MATERIALIZED VIEW every five minutes and a shrug. It works. It also rebuilds the entire view every time, even when one row changed since the last run. If you've ever watched that refresh crawl on a big table and wondered why Postgres can't just apply the one change, this post is for you.

Short version: it can, with an extension called pg_ivm. It keeps a materialized view current inside the same transaction that changes the base table, using triggers instead of a scheduled rebuild. The project shipped version 1.16 this month with PostgreSQL 19 support. I read the whole README rather than the release note, because the restrictions section is where this extension is won or lost. I haven't put it in front of a client database yet, so everything below is what the docs promise and what I'd test.

The problem with REFRESH MATERIALIZED VIEW

A normal materialized view is a snapshot. You create it from a query, Postgres stores the result as a table, and it stays frozen until you run REFRESH MATERIALIZED VIEW. That command recomputes the full query and swaps in the result. With the CONCURRENTLY option readers aren't blocked, but the work is still a full recompute.

The pg_ivm README has a timing example that shows the gap well. These are the project's numbers on a pgbench dataset with 10 million account rows, not mine, so treat them as the shape of the thing rather than a promise for your hardware. Updating one account row took about 9 ms. Refreshing the plain materialized view afterwards took 20.5 seconds. That is the whole reason the polling approach feels wrong: one row changed, and you paid for ten million.

The usual workaround is what I did. Refresh on a timer, accept stale reads, and pick the timer by arguing with whoever owns the dashboard. Postgres has no built-in alternative, because incremental maintenance of arbitrary queries is a hard problem. That's the gap pg_ivm fills.

What pg_ivm does differently

The README calls the result an Incrementally Maintainable Materialized View, or IMMV. You create one with a function instead of CREATE MATERIALIZED VIEW:

-- before: a plain materialized view, refreshed by cron
CREATE MATERIALIZED VIEW mv_normal AS
  SELECT a.aid, b.bid, a.abalance, b.bbalance
  FROM pgbench_accounts a JOIN pgbench_branches b USING (bid);

-- after: an incrementally maintained one
SELECT pgivm.create_immv('immv',
  'SELECT a.aid, b.bid, a.abalance, b.bbalance
   FROM pgbench_accounts a JOIN pgbench_branches b USING (bid)');

Behind that function call the extension creates triggers on the base tables. When you INSERT, UPDATE or DELETE a row, an AFTER trigger works out which rows in the view are affected and patches only those. The docs call this immediate maintenance, because the view is updated in the same transaction as the change. There is no window where a reader sees the base table and the view disagree.

In the README's example, the single-row update on the base table took about 15 ms with the IMMV in place, up from 9 ms without it. So you pay roughly six extra milliseconds on every write to get a view that is always current and never needs a 20-second refresh. Whether that trade is good depends entirely on how often the base table changes, which I'll get to.

The extension supports PostgreSQL 13 through 19. Installation is make install plus CREATE EXTENSION pg_ivm;, and the docs recommend adding it to shared_preload_libraries or session_preload_libraries so maintenance works correctly. That needs a restart, so plan it for a maintenance window.

The index you must not forget

This is the part of the README I'd highlight with a marker. Incremental updates need to find the right row in the view quickly, and without an index on the view that lookup is a sequential scan. The README shows it directly. With the automatically created index in place, a single-row update took 15 ms. After dropping that index, the same update took about 3.2 seconds.

create_immv tries to build a unique index for you when it can derive a key from the query. A GROUP BY gives it the grouped columns, a DISTINCT gives it all the columns, and otherwise it looks for all the primary key columns of the base tables in the select list. When it can't find one, it prints a notice telling you to create an index yourself. Please read that notice. If you ignore it, every write to a base table will quietly get slower, and you'll blame the wrong thing.

The practical rule I'd follow: include the primary keys of your base tables in the select list, check \d on the new view straight after creating it, and confirm an index exists before you call it done.

Aggregates work, with one slow case

Dashboards are mostly aggregates, so this matters. The README shows a GROUP BY view with count, sum and avg, where updating one account row took about 17 ms and the aggregated numbers for that branch were correct immediately afterwards. The supported aggregates are count, sum, avg, min and max, and only built-in ones.

Two details deserve attention. First, min and max. If you delete the row that currently holds the minimum or maximum, Postgres may have to recompute that group from the base tables, and the docs warn that this can take a long time. So a view full of max() columns on a table where rows get deleted is the wrong candidate.

Second, floating point. The docs say using sum or avg on real or double precision columns is unsafe, because the incrementally maintained value can drift from what a fresh calculation would give. Use numeric instead. Money columns should be numeric already, but I'd audit anything else that feeds an IMMV.

The extension also adds hidden columns named like __ivm_count__ to aggregate views, which it uses to maintain the numbers. Don't select them in your own queries, and don't be surprised when you see them in \d.

Restrictions that will bite you

The supported SQL is a subset. Inner and outer joins, DISTINCT, simple subqueries in FROM, EXISTS and simple CTEs are fine. Window functions, HAVING, ORDER BY, LIMIT, UNION and friends are not allowed. The base tables must be plain tables, which rules out views, partitioned tables and foreign tables. If your biggest table is partitioned, that alone may end the experiment, and I'd rather find that out on day one.

Outer joins have extra rules: only a simple equijoin, and no aggregates in the same view. Logical replication isn't supported either, so an IMMV on a subscriber won't update when the publisher's base table changes.

Concurrency is the one I'd read twice. Under READ COMMITTED, the extension takes an ExclusiveLock on the view right after a base table changes, so two transactions touching the same IMMV are serialised. Under REPEATABLE READ or SERIALIZABLE, it raises an error instead of waiting if it can't get the lock. That's a correctness choice and a sensible one, but it means a hot table feeding an IMMV can become a queue. The README also says plainly that this is a poor fit when the base table is written to frequently or in large batches.

Bulk loads, dumps and upgrades

The README gives a clean escape hatch for big writes. Call pgivm.refresh_immv('name', false) to drop the triggers, load your data, then call it again with true to rebuild and re-enable maintenance. For a nightly import that's a normal pattern, and I'd script it.

One more operational detail: the extension's own metadata isn't included in pg_dump output. Before a dump or pg_upgrade you run the bundled pg_ivm_dump_metadata script, and after the restore you run the SQL it produced. If you skip that step, the view's data comes back as an ordinary table with no triggers, and it quietly stops updating. I'd add that to the backup runbook before the first IMMV goes live. If you are still on the basics, my Postgres tuning notes cover the parameters I actually touch, and this extension is another reason to do a real restore drill.

When I'd use it and when I wouldn't

I'd reach for pg_ivm when a view joins a few tables, the base tables change at a modest rate, readers need fresh numbers, and a 20-second rebuild is not acceptable. A customer-facing totals page is the textbook case. I'd keep a cron-refreshed materialized view when the data is allowed to be a few minutes old, the base tables take heavy writes, or the query uses features the extension doesn't support. Plain old stale-but-cheap is a perfectly good answer for a lot of internal reporting.

Try it this week

Pick one materialized view you currently refresh on a timer and check it against the restriction list above: no window functions, plain base tables, only the five aggregates. If it passes, restore a copy of the database onto a scratch server, install the extension, create the IMMV with a primary key in the select list, and time your real write workload against it. Compare the extra write latency with what your refresh job costs today. If you'd like to see the kind of client database work this sits inside, my portfolio is the place to start.

Originally published at abrarqasim.com. I write there about React, PHP, Rust, Go and the AI tooling around them.

Restic Backup for a Small VPS: Script, Retention and Restore Test

Qasim Parray — Thu, 15 Oct 2026 08:38:40 +0000

A backup you have never restored is a hope, not a backup. I have said that sentence to clients so many times that it has stopped sounding like advice and started sounding like a tic. Yet when I open a new server for someone, the backup situation is usually one of two things: nothing, or a nightly tar job that has been filling a disk since 2023 and has never been opened.

If you run a small VPS and want a restic backup setup that you can set up in an evening and trust afterwards, this is the one I'd use. I'll cover what restic is doing under the hood in just enough detail to make the commands make sense, then the backup script, the retention policy, a Postgres dump piped straight in, and the part everyone skips: checking and restoring.

I should be upfront about scope. This is for small self-hosted setups, one or a few servers, data measured in gigabytes. If you run a database cluster with point-in-time recovery requirements, a file-level tool is the wrong layer for the database and you should look at WAL archiving instead. For everything else on the box (uploads, configs, compose files, a database dump), restic is a calm choice.

Why restic suits a small VPS

Restic stores your data as encrypted, deduplicated snapshots in a repository. Deduplication means a second backup of mostly unchanged files transfers and stores very little, which is why you can run it nightly without watching your storage bill climb. The repository can sit on a local disk, an SFTP server, or an object store, and the restic documentation on preparing a repository lists the supported backends.

I put the repository somewhere that is not the server being backed up. That sounds obvious, and I have still seen backups stored on the same disk as the data. A disk failure, a ransomware incident or a fat-fingered rm -rf takes both. A storage box or object bucket from a different provider costs a few dollars a month and removes that whole category of failure.

Initialise once:

export RESTIC_REPOSITORY="sftp:backup@storagebox.example.com:/restic/myserver"
export RESTIC_PASSWORD_FILE="/etc/restic/password"

restic init

Keep the password file readable by root only, and keep a second copy of the password somewhere that is not that server, such as your password manager. Restic encrypts the repository, so losing the password means losing every backup. I have not had to test how final that is, and I don't plan to.

The backup script

Here is the script I start from. It is plain Bash on purpose.

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

export RESTIC_REPOSITORY="sftp:backup@storagebox.example.com:/restic/myserver"
export RESTIC_PASSWORD_FILE="/etc/restic/password"

# 1. Files: configs, uploads, compose projects
restic backup \
  --tag files \
  --one-file-system \
  --exclude-file /etc/restic/excludes.txt \
  /etc /srv /home/deploy

# 2. Database: dump straight into the repository, no temp file
restic backup \
  --tag postgres \
  --stdin-from-command \
  --stdin-filename myapp.sql \
  -- sudo -u postgres pg_dump --format=plain myapp

# 3. Retention
restic forget \
  --tag files --keep-daily 7 --keep-weekly 4 --keep-monthly 6 --prune
restic forget \
  --tag postgres --keep-daily 14 --keep-weekly 8 --keep-monthly 12 --prune

A few choices in there are worth explaining.

The --one-file-system flag. The restic backup documentation says it stops restic from crossing filesystem boundaries and subvolumes. On a VPS that keeps it from wandering into mounted volumes, network shares or /proc-style virtual filesystems you never meant to back up. If you do have a second volume with data you want, list its mount point explicitly as another path.

The exclude file. Things like node_modules, build caches, *.log, and Docker's own storage directory should stay out. You back up your compose files and volumes, not /var/lib/docker/overlay2. The same docs page describes --exclude-file as a file listing items to skip, one pattern per line.

The Postgres dump. The same documentation explains that --stdin-from-command makes restic run a command and store its output, and that you must put -- before the command so restic doesn't parse its arguments. That removes the temp file I used to write to disk, which was always a second copy of the database sitting around waiting to be forgotten. My own bit of caution here: a plain-format dump of a large database is slow to restore. For anything past a few gigabytes I'd switch to pg_dump --format=custom and restore with pg_restore, which also lets you restore a single table.

Tags. I tag file snapshots and database snapshots differently, then apply different retention to each. The docs mention tags as a way to attach identifying information and to select snapshots in forget, and I use them for exactly that.

Retention without surprises

Retention is where I've seen people shoot themselves. The restic forget documentation explains the policy flags: --keep-daily n keeps the most recent snapshot for each of the last n days that have snapshots, with matching weekly and monthly flags. It also notes that forget --prune removes the data that was referenced only by the snapshots you dropped, which can take a while on a large repository.

Two cautions from that documentation shape how I use it. First, a policy applies to snapshots grouped by host and paths by default, so if you change your backup paths later, you create a new group, and the old one is no longer being pruned by the same rules. I run restic snapshots after any path change and look at what groups exist. Second, run forget with --dry-run the first time. Reading the list of what would be removed costs nothing.

My defaults are a week of dailies, a month of weeklies and half a year of monthlies for files, and a bit longer for database dumps, since those are the thing clients ask for after a mistake. Adjust for what your data is worth and how long you'd take to notice a problem. If a bug quietly corrupts data and you notice a month later, a seven-day retention doesn't help you.

Scheduling it

I use a systemd timer instead of cron, mainly because a failed run shows up in systemctl status and the journal without extra work.

# /etc/systemd/system/restic-backup.service
[Unit]
Description=Restic backup
After=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/restic-backup.sh

# /etc/systemd/system/restic-backup.timer
[Unit]
Description=Nightly restic backup

[Timer]
OnCalendar=*-*-* 03:15:00
RandomizedDelaySec=15min
Persistent=true

[Install]
WantedBy=timers.target

Enable it with systemctl enable --now restic-backup.timer. Cron works just as well if that's what you already have. What matters is that something tells you when it fails. I add a final line to the script that pings a monitoring URL on success, so a missed backup raises an alert through silence. Dead man's switches are underrated.

Check the repository, then restore something

Two commands separate a backup from a hope. The first is restic check, which verifies the repository structure. The documentation on working with repositories describes --read-data-subset, which checks a portion of the pack files per run, for example --read-data-subset=1/5 on Monday, 2/5 on Tuesday and so on, so each night reads a fifth of the data and a full pass completes in five runs. That is a sane compromise when reading everything would cost bandwidth.

The second is a restore test, and I'd do it monthly:

restic restore latest --tag files --target /tmp/restore-test --include /etc/nginx
restic dump latest myapp.sql --tag postgres | head -n 20

Restore into a scratch directory, open the files, load the dump into a throwaway database, and check a row count against production. Write down how long it took. That number is your real recovery time, and it's the one you'll want in your head when something breaks at night.

Do this tonight

Pick one server. Create a repository on storage that lives somewhere else, run restic init, and run the script above by hand with the file backup only. Then restore one directory to /tmp and compare it with the original using diff -r. Once that works, add the database line, then the timer. If you want a second pair of eyes on a setup like this for a client system, I take on infrastructure work, and you can find more about it on my portfolio. If your data lives in Postgres, my post on what stays plaintext under encryption at rest is a useful companion, because backups need the same care as the live database.

Originally published at abrarqasim.com. I write there about React, PHP, Rust, Go and the AI tooling around them.

WhatsApp Business API Automation in n8n: Start With the Window

Qasim Parray — Wed, 14 Oct 2026 16:38:38 +0000

Every few weeks a small business owner tells me the same thing: "We get hundreds of WhatsApp messages and we answer them by hand. Can you automate it?" The honest answer is yes, partly, and the part you automate matters more than the tool you pick. I have watched more than one WhatsApp bot idea die because it was designed as a chatbot first and a messaging channel second.

WhatsApp business API automation has rules that web chat doesn't. There is a clock on every conversation, there is pricing per delivered message, and there are template messages that need approval before you can send them cold. If you wire up a flow in n8n without those in your head, you will build something that works on your own phone and falls over on the third real customer.

This is the order I'd tackle it in now: rules first, then the workflow, then where a language model fits, and where it shouldn't. I'm describing the shape here, not a finished product, and I'll flag the places where I'm relying on documentation I couldn't fully read.

Start from the 24-hour window

The single most useful fact about the platform is the customer service window. According to the WhatsApp Business Platform pricing page, when a user messages a business it opens a 24-hour window in which the business can reply with service messages at no charge, and the window resets with each new user message.

That sentence should drive your design. Inside the window you can send free-form replies, which is where an AI draft or an automated answer is natural. Outside it, you can only start a conversation with an approved template message, and that category of message is billed.

So the first question for any automation is: does this flow answer people, or does it start conversations? Answering is cheap and conversational. Starting conversations is a marketing and compliance decision that deserves its own planning. I build the answering flow first because it has a clear boundary, and the customer already asked for the interaction.

What you actually pay for

I'd rather you read the pricing page yourself than trust my summary, but the structure is worth knowing before you promise a client a monthly figure. The same page says businesses are charged per message delivered (not sent), rates depend on the destination market and the message category, and there are four categories: marketing, authentication, utility and service. It also says service messages are not charged, and that messages in the three days after a customer arrives through an ad that clicks to WhatsApp are free.

Pricing models like this have changed more than once, and the page I read is the one that applies today, not necessarily next quarter. When I quote automation work I give the client a range, tell them where to look up the current rates for their country, and keep the platform fees on a separate line from my own fee. Rolling them together makes my quote look wrong every time Meta changes a number.

A small n8n shape that works

The pattern I use is boring on purpose. A webhook receives the incoming message. A short chain of nodes decides what kind of message it is. One branch answers common questions from a fixed source, and another branch hands the conversation to a human.

n8n has a built-in WhatsApp Business Cloud node whose documented operations include sending a message, sending a template, a send-and-wait-for-response operation, and uploading, downloading and deleting media. For receiving messages you pair it with a webhook. Meta's webhook guide is where the handshake and payload format live. I can't reproduce those details with confidence because that page renders in the browser and I'd rather you read it than copy my paraphrase.

Two things I always add, because webhook senders in general retry and attackers in general guess URLs.

First, verify that the request came from Meta. Incoming requests carry a signature header you can check against your app secret. In an n8n Code node the check looks roughly like this:

const crypto = require('crypto');

const secret = $env.WHATSAPP_APP_SECRET;
const received = $json.headers['x-hub-signature-256'] || '';
const expected = 'sha256=' + crypto
  .createHmac('sha256', secret)
  .update($json.rawBody)
  .digest('hex');

const ok = received.length === expected.length &&
  crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));

if (!ok) throw new Error('bad signature');
return $input.all();

The hard part is rawBody. The signature is computed over the exact bytes Meta sent, so a node that parses the JSON and re-serialises it gives you a different string and a check that always fails. Turn on the raw body option in the Webhook node settings and test with a real message, not a hand-made curl request.

Second, deduplicate. If your workflow is slow and the sender decides it hasn't heard back, you can see the same message twice. I store each message ID in a small Postgres table and skip anything already seen:

INSERT INTO wa_seen (message_id) VALUES ($1)
ON CONFLICT (message_id) DO NOTHING
RETURNING message_id;

If the insert returns no row, the flow stops. That one query is what stops a customer getting the same reply twice. I wrote about a nastier n8n failure, where a quiet bug cost a client days, in my n8n workflow post. The lesson there applies here: log every message ID and every branch decision, because you will need that log.

Where a language model fits

A model is good at one WhatsApp job: reading a messy customer message and drafting a reply from a source you control, such as an FAQ page or a price list. It is bad at deciding things the business is accountable for, like refunds, delivery promises or anything legal.

My rule is that the model drafts and a person sends, until the numbers say otherwise. The n8n docs describe a send-and-wait operation that pauses the workflow until a person approves or provides input, and the same page notes the node can serve as a human review step for AI agent tool calls. That fits this pattern directly: the draft goes to a staff member on WhatsApp, they tap approve or edit it, and only then does the customer see it.

After a few weeks of watching approvals, you'll know which question types are approved almost untouched. Those are the ones you can move to automatic replies. Everything else stays in review. If the idea of judging whether an agent is good enough makes you uneasy, I wrote up a method in grading the database, not the reply, and it carries over to chat flows.

What to leave out of version one

Leave out cold outreach. Leave out the model answering anything about money or health. Leave out clever intent classifiers until you have a few hundred real messages to look at. Version one should do three plain things: receive, answer from a fixed source inside the window, and hand off to a human with the full thread attached.

I'd also leave out voice notes and images at first. They are common on WhatsApp, and they'll arrive anyway, so your flow needs a polite fallback that says a person will look at it soon. Media handling is a good second project, once the text flow is quiet.

When not to automate at all: if the business gets thirty messages a day and one person answers them well, a bot costs more attention than it saves. Automation pays back when volume is high and questions repeat.

Build this first

This week, take one real client or your own business and export fifty recent WhatsApp conversations. Sort the first messages into groups by what the customer wanted. If one or two groups cover most of the volume, you have a scoped automation. Write the three answers those groups need, put them in a table, and build the receive-verify-deduplicate-answer chain in n8n against Meta's test number. Show a human the drafts before anything is sent. If you want help turning that into a production flow for your own business, my other automation projects are listed on my portfolio.

Originally published at abrarqasim.com. I write there about React, PHP, Rust, Go and the AI tooling around them.

Freelance Contract Template: Six Questions I Settle Before I Sign

Qasim Parray — Wed, 14 Oct 2026 08:38:38 +0000

Here is a confession from a developer who has signed more than one contract he did not fully read. The first time a client disputed an invoice with me, I opened my "contract" and found a two-line email thread and a Google Doc titled "Scope v3 FINAL". Neither said when I was supposed to be paid. Neither said who owned the code. I got paid eventually, but only because the client was decent, and that is not a contract, it is luck.

If you freelance in web development, you need a contract template you actually trust, and you need it before the first discovery call turns into a project. I'm not a lawyer, and nothing here is legal advice. What follows is the checklist I run through before I sign anything, with the clauses I've seen cause the most pain, and a few pointers to primary sources so you can check my claims instead of taking my word for them.

A freelance contract template does not need to be long. Mine is about two pages. It needs to answer six questions in plain English, and the rest of this post walks through them.

What a short contract has to settle

A good contract is a list of decisions you made while you were both still friendly. Every clause exists because, at some point, two reasonable people remembered a conversation differently.

The six questions I want answered in writing are these. What exactly am I building, and what happens when the request changes? When and how do I get paid? Who owns the result, and when does ownership transfer? What happens if either of us stops? Who is responsible if something breaks after launch? And, for work in some places, does the law already require something I forgot?

If you want a version of the first question that wins you the job rather than just protecting you, I wrote about the proposal side in my web development proposal template post. The contract is the quieter sibling: it only matters when something goes sideways.

Scope and the change clause

Scope descriptions fail when they describe features instead of outcomes and boundaries. "A contact form" is a feature. "A contact form that sends to one address, with a spam filter, no file uploads, no CRM integration" is a scope.

I list deliverables, then I list what is explicitly excluded, then I add a change clause. The change clause is short:

Work outside the deliverables listed in section 2 is a change request.
I will estimate it in writing. Work on a change request starts after
you approve the estimate by reply email. Approved changes are billed at
the rate in section 3 and may move the delivery date.

That paragraph does more for scope creep than any amount of firmness in a meeting. It turns "can you just also..." into a question with a price attached, and it makes me the person offering an estimate rather than the person saying no. I went through the human side of that problem in my scope creep post, and the short version is that a one-line email estimate beats a long conversation every time.

One more thing about scope: put the number of revision rounds in the contract. "Unlimited revisions" is a sentence that sounds friendly and ends careers.

Payment terms that survive a slow client

Payment clauses are where most freelancers are too polite. Mine has five parts, and I'd keep all five.

A deposit before work starts. I take a third on signing for projects under a few weeks, and I never begin without it. The deposit is not about money, it is a cheap test of whether the client can send a payment at all.

Milestone invoices tied to deliverables, not to calendar dates. If I invoice on "the 15th" and the client has not reviewed anything, I'm invoicing for a promise.

Net terms in days, stated as a number. "Payable within 14 days of invoice date" beats "promptly" because you can count to 14.

A late fee or a pause clause. I use a pause clause: if an invoice is more than seven days overdue, work pauses and the delivery dates move by the length of the pause. It's gentler than interest and more effective, since clients rarely care about a 1.5% fee but do care about their launch date.

Currency and fees. If you work across borders, say who pays the bank and platform charges. I've lost a surprising amount of an invoice to transfer fees nobody mentioned.

For how I decide the numbers that go into those clauses, see how I price freelance web development work.

Who owns the code

This is the clause people copy from the internet and get wrong, so I'll go slowly.

Many templates say the work is "work made for hire". That phrase has a specific meaning in US law. The statute's definition, in 17 U.S.C. section 101, covers works made by an employee within the scope of employment, and a short list of commissioned categories (a contribution to a collective work, a translation, a compilation, an instructional text and a few others) where the parties agreed in a signed writing. Custom website or application code does not obviously sit in that list. The US Copyright Office's Circular 30 on works made for hire is a readable explanation, and it is worth five minutes before you paste a boilerplate sentence into your agreement.

What I use instead is an assignment clause that transfers ownership on full payment, plus a licence for anything I bring with me:

On receipt of full payment, I assign to you the copyright in the
deliverables created specifically for this project. I keep ownership of
my pre-existing tools, libraries and templates, and grant you a
perpetual, non-exclusive licence to use them as part of the deliverables.

Two details matter. "On full payment" ties ownership to the thing you care about. And the carve-out for pre-existing tools means you can reuse your own deploy scripts and component library on the next job without being accused of selling something twice.

Other countries have different rules, and whether a clause like that holds up depends on where you and your client live. If the project is large, pay a lawyer for an hour to read your template once. That hour is cheap compared with one dispute.

Ending the project early

Every contract needs an exit. Mine allows either side to end the agreement with seven days written notice. On termination, the client pays for work completed to that point, plus a kill fee, which I set at a flat percentage of the unbilled remainder for fixed-price projects. The kill fee isn't a punishment. It reflects that I turned down other work to hold the slot.

I also add a line that deliverables, source code and credentials are handed over only after the final invoice is settled. Clients occasionally see that as aggressive, and I explain it as the same rule that governs ownership.

What the law may already require

Some places now require a written contract for freelance work. New York State is one example: its Department of Labor page on the Freelance Isn't Free Act says the act added Article 44-A to the General Business Law in August 2024, with contract requirements and a formal enforcement process, and that the department published a model contract. I haven't read the whole statute closely, and your own jurisdiction might have something similar or nothing at all. Searching your state or country plus "freelance written contract law" takes five minutes and might turn up a requirement you didn't know about.

Treat the model contract from a government site as a free checklist even if it doesn't apply to you. Compare it against yours and see what's missing.

Do this before your next call

Open your last signed agreement, or the email thread that passed for one. Hold it up against the six questions near the top of this post. Where you find a gap, write the missing clause in two sentences, and paste it into a template file you will actually reuse. Then send the next client that template before the kickoff call, not after. If you want to see how I structure the work that comes after the contract, the rest of my projects are on my portfolio.

Originally published at abrarqasim.com. I write there about React, PHP, Rust, Go and the AI tooling around them.

Zero Downtime Deployment on One VPS With Compose and Caddy

Qasim Parray — Tue, 13 Oct 2026 16:38:36 +0000

For a long time my deploy process on small client servers was one command and a prayer. I would SSH in, run docker compose up -d --build, watch the logs scroll, and tell myself that a few seconds of broken pages was the price of shipping. Then a client opened their own site mid-deploy, got a bare 502 from the proxy, and sent me a screenshot with no text at all. The silence was worse than an angry message.

Zero downtime deployment sounds like something you need Kubernetes for. You don't. On a single VPS you can get to the point where a deploy is invisible to visitors using two things you probably already run: Docker Compose and a reverse proxy that does health checks. I use Caddy for this, and the setup below is what I now put on every new box.

I should say up front what this is not. It isn't a database migration strategy, and it won't save you from a deploy that ships a broken build with a healthy-looking /health route. It handles the boring, common case: replacing the app container without dropping requests.

Why a plain compose up drops requests

When you change an image and run docker compose up -d, Compose stops the old container and starts a new one in its place. There is a gap. The old process gets SIGTERM, the new process boots, loads its config, warms its connections, and only then starts listening. Anything that arrives between those two moments hits a closed port.

The proxy in front of it makes this visible. Caddy tries to connect to web:3000, gets refused, and returns a 502. Nothing is wrong with Caddy. It did exactly what it was told.

The fix has to cover two separate problems. First, the old container must stay alive until the new one is ready. Second, the proxy must know which containers are ready, and send traffic only to those. Most "zero downtime" tutorials solve the first and forget the second, which is how you end up with two containers running and requests still landing on the one that is halfway through booting.

Start with a health check that means something

Compose can wait for a container to be healthy before it considers the deploy finished. The Compose service reference documents healthcheck with interval, timeout, retries, start_period and start_interval. That last one only exists from Compose 2.20.2, so check your version on old servers before you rely on it.

Here is the service I start from:

services:
  web:
    image: registry.example.com/myapp:${TAG}
    restart: unless-stopped
    stop_grace_period: 30s
    healthcheck:
      test: ["CMD", "wget", "-qO-", "http://localhost:3000/health"]
      interval: 5s
      timeout: 3s
      retries: 3
      start_period: 20s
    networks: [internal]

  caddy:
    image: caddy:2
    ports: ["80:80", "443:443"]
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
    networks: [internal]

networks:
  internal:

volumes:
  caddy_data:

Two details matter here. The web service publishes no host port, so two copies of it can run side by side without fighting over a port. And stop_grace_period gives the old container time to finish in-flight requests after it receives SIGTERM, instead of Docker's default ten seconds.

I wrote a longer rant about what depends_on actually waits for in my post on Compose health checks. The short version: a container that has started is not a container that can serve a request, and your /health route needs to check something real. A route that returns 200 without touching the database is a smoke detector with the battery taken out.

Let Caddy find both copies

Compose gives every service a DNS name on the network. If web has two running containers, a lookup for web returns two addresses. Caddy's reverse_proxy can use that directly with the dynamic a upstream source, which the reverse_proxy docs describe as querying a domain name and refreshing the cached results on an interval (the default is one minute, which is far too slow for us).

example.com {
    reverse_proxy {
        dynamic a web 3000 {
            refresh 2s
        }
        lb_policy round_robin
        lb_try_duration 5s
        lb_try_interval 250ms

        health_uri /health
        health_interval 2s
        health_fails 1
        health_passes 2
    }
}

The pieces do different jobs. refresh 2s makes Caddy notice new containers quickly. The active health check (health_uri plus health_interval) marks an upstream as down when /health fails, so a container that is still booting gets no traffic. And lb_try_duration tells Caddy to keep trying to pick a healthy backend for up to five seconds instead of failing immediately. The docs are clear that retries are off by default, so this line is doing real work. A visitor who arrives in the middle of the swap waits a moment rather than seeing an error page.

I'm not fully sure refresh 2s is the right number for every setup. Two seconds worked on the small boxes I run. On a busy server with many services, more DNS lookups might matter, and I haven't measured that.

The deploy script

With that in place, the deploy is three steps: start a second copy, wait until it is healthy, then remove the old one.

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

export TAG="$1"
docker compose pull web

# Remember which containers are running the old version
OLD=$(docker compose ps -q web)

# Add a second copy built from the new tag, keep the old one untouched
docker compose up -d --no-deps --no-recreate --scale web=2 --wait --wait-timeout 90 web

# New copy is healthy, so retire the old ones
docker stop --time 30 $OLD
docker rm $OLD

# Let Compose settle back to a single replica
docker compose up -d --no-deps --no-recreate --scale web=1 web

The order of those lines is the whole trick, so here is why each one is there.

Recording OLD before anything else matters because Compose, not you, decides which container to remove when you scale down. If you scale to one and let it choose, there is no promise it picks the old one. Writing the IDs down first means you stop exactly the containers you meant to. I learned this by reading the output of docker ps after a test deploy and noticing the container with the newer image was the one that had disappeared. That was a staging box, which is the only reason it was funny.

The --no-recreate flag is what keeps the old container alive. The docker compose up reference says it stops Compose from recreating containers that already exist. Because TAG has changed, the extra replica that gets created is built from the new image, and the existing one keeps serving until we stop it.

The --wait flag is the gate. According to the same reference it waits for services to be running or healthy and implies detached mode, with --wait-timeout as the upper bound. If the new container never becomes healthy, the command fails, set -e ends the script, and the old container is still serving. A failed deploy that changes nothing is a good failure. You can also roll back by exporting the previous tag and running the script again, since the script has no memory of what came before.

Prove it with a loop

I don't trust a zero downtime claim I haven't watched. Before the first real deploy, run a dumb load loop in one terminal and the deploy in another:

while true; do
  curl -s -o /dev/null -w "%{http_code} %{time_total}\n" https://example.com/
  sleep 0.2
done | tee deploy-check.log

Afterwards, grep -v '^200' deploy-check.log shows every request that didn't succeed. Look at the time column too. During the overlap you may see a few requests that take a second or two instead of a few milliseconds. That is lb_try_duration quietly doing its job, and it is the difference between a slow page and a broken one. If you see 502s, check the three usual suspects in order: the health route returns 200 before the app can really serve, refresh is still at its default minute, or lb_try_duration is missing.

I also keep a second loop that hits an endpoint which needs the database, because a lot of apps answer a static route happily while their connection pool is still empty.

What this doesn't cover

Be honest with yourself about three gaps.

Database migrations. If the new code needs a column the old code does not know about, both versions run at the same time for a short window. Write migrations that the old code can survive: add columns first, remove them in a later deploy.

Long-lived connections. WebSockets and server-sent events will be cut when the old container stops. Clients need to reconnect, and they should. If yours don't, that is a bug you have anyway.

State on disk. If the app writes uploads to a local volume, two containers share that volume, which is fine for reads and a hazard for anything else.

If this all feels like a lot of ceremony for one app, there are tools that wrap it for you. I compared two of them after migrating a client, in the Coolify vs Dokploy write-up. I still prefer the raw script for boxes where I want to understand every moving part.

Try it this week

Pick one low-traffic service on a VPS you control. Add a real health route, remove its host port, put Caddy in front with dynamic a and lb_try_duration, and run the script above while hitting the site with curl in a loop from another terminal. Count the non-200 responses. If you get zero, you now have a deploy you can run at noon on a Tuesday. If you get some, the loop output tells you exactly which of the pieces is missing. I do this kind of infrastructure work for clients, and you can see more of it on my portfolio.

Originally published at abrarqasim.com. I write there about React, PHP, Rust, Go and the AI tooling around them.