DEV Community: adeutou

nx-safe-suite: A Deep Dive Into Five Production-Grade Next.js Packages

adeutou — Wed, 12 Aug 2026 13:23:08 +0000

How each package works, why it is designed the way it is, and what it replaces.

This is the second article in a two-part series. The first covers the architecture and the reasoning behind the project. This one goes into the implementation of each package.

@nx-safe-suite/env: Validation That Stops the Process

The problem

process.env is a Record<string, string | undefined>. Every access is potentially undefined. The standard response to this is to sprinkle ?? and ! operators throughout the codebase, which does not make the code safer. It makes it longer and harder to read while the underlying risk remains.

The real problem is that environment validation happens too late. By the time a missing variable causes an error, the request is already in flight, the user is already waiting, and the stack trace points somewhere unrelated.

The solution

@nx-safe-suite/env validates the entire environment at startup, before the application does anything else. If validation fails, the process exits with a readable report:

❌ Invalid environment variables:

  DATABASE_URL
    → Required
  API_SECRET
    → String must contain at least 10 character(s)

2 variables failed validation. Fix your .env file and restart.

No stack trace. No cryptic undefined error three function calls deep. Just the problem, described in terms of the configuration, not the code.

The design decision worth noting

The package separates server and client schemas. This is not cosmetic. Next.js exposes NEXT_PUBLIC_* variables to the browser bundle. Any variable not prefixed with NEXT_PUBLIC_ is stripped at build time. If you define a schema for a non-prefixed variable under client, the package throws synchronously at startup, before the application runs, because you have described a variable as browser-accessible that Next.js will never expose to the browser.

export const env = createEnv({
  server: {
    DATABASE_URL: z.string().url(),
    API_SECRET:   z.string().min(10),
  },
  client: {
    NEXT_PUBLIC_API_URL: z.string().url(),
  },
  runtimeEnv: process.env,
});

The return value is a frozen, fully typed object. env.DATABASE_URL is a string, not a string | undefined. TypeScript knows this. Your editor knows this. The runtime guarantees it.

One additional detail: importing env.ts from next.config.js means a misconfigured environment fails the build, not just the boot. The error appears in CI before any code is deployed.

@nx-safe-suite/api-response: A Contract Your Frontend Can Rely On

The problem

In a codebase with multiple developers and multiple API routes, response shapes drift. One route returns { data: [...] }. Another returns { results: [...] }. A third returns the array directly. Error responses are strings, objects, or HTTP status codes alone, depending on who wrote the route and when.

Frontend developers work around this with defensive parsing, optional chaining, and condition checks at every call site. The problem compounds over time.

The solution

A small set of typed helpers that always produce the same shapes.

Success responses follow a consistent envelope:

{
  "data": { "id": "123", "name": "Albert" },
  "meta": { "timestamp": "2026-07-07T12:00:00Z" },
  "links": { "self": "/api/users/123" }
}

Error responses follow RFC 9457, the IETF standard for HTTP problem details, extended with a code field for machine-readable business errors:

{
  "type": "about:blank",
  "title": "Not Found",
  "status": 404,
  "detail": "User 123 was not found.",
  "instance": "/api/users/123",
  "code": "USER_NOT_FOUND"
}

The code field is what makes error handling tractable on the frontend. Instead of parsing status codes or error message strings, client code can switch on a stable, documented identifier.

export async function GET(_req: Request, { params }: { params: { id: string } }) {
  const user = await db.user.findUnique({ where: { id: params.id } });

  if (!user) return notFound({
    code: "USER_NOT_FOUND",
    detail: `User ${params.id} was not found.`,
    instance: `/api/users/${params.id}`,
  });

  return ok(user, { links: { self: `/api/users/${user.id}` } });
}

Pagination, both offset and cursor, is handled as a pagination option on any success helper. The response meta block is extended automatically with the computed values (totalPages, hasNextPage, hasPrevPage). No manual calculation at the call site.

@nx-safe-suite/route-guard: Authentication Without the Boilerplate

The problem

A typical Next.js API route that requires authentication, role checking, and input validation looks like this before any business logic runs:

export async function POST(req: Request) {
  const session = await getServerSession(authOptions);
  if (!session?.user) {
    return Response.json({ error: "Unauthorized" }, { status: 401 });
  }
  if (!session.user.roles.includes("admin")) {
    return Response.json({ error: "Forbidden" }, { status: 403 });
  }
  let body: unknown;
  try {
    body = await req.json();
  } catch {
    return Response.json({ error: "Invalid JSON" }, { status: 400 });
  }
  const parsed = CreateProjectSchema.safeParse(body);
  if (!parsed.success) {
    return Response.json({ error: parsed.error }, { status: 422 });
  }
  // business logic begins here
}

This is forty lines before any actual work is done. It is also inconsistent across routes, because every developer writes their version of this slightly differently.

The solution

createGuard produces a configured withGuard wrapper. The cross-cutting concerns, auth, roles, rate limiting, and validation, are declared as configuration. The handler receives a typed context object containing only what it needs.

const guard = createGuard({
  jwt: { secret: env.JWT_SECRET },
  rateLimit: { max: 100, window: "1m" },
});

export const POST = guard.withGuard(
  {
    roles: ["admin"],
    body:  z.object({ name: z.string().min(1) }),
  },
  async (req, { user, body }) => {
    // user is GuardUser: typed, verified
    // body is { name: string }: validated
    const project = await db.project.create({
      data: { name: body.name, ownerId: user.id },
    });
    return created(project, { links: { self: `/api/projects/${project.id}` } });
  },
);

The RBAC check accepts either a string array, where any match grants access, or an async function, which enables attribute-based access control without a separate library:

roles: async (user) => {
  const membership = await db.membership.findFirst({
    where: { userId: user.id, organizationId: params.orgId },
  });
  return membership?.role === "owner";
}

Server Actions are supported via withAction. The same auth and RBAC pipeline runs without a real Request object, which Server Actions do not have, and the action receives a typed context containing the resolved user and the input.

The rate limiter is an in-memory LRU store by default. The interface is pluggable: swap it for Upstash or ioredis in a distributed deployment by implementing four methods. The default is good enough for single-instance deployments and zero-dependency prototyping.

@nx-safe-suite/server-cache: Multi-Tier Caching That Composes

The problem

Next.js has excellent built-in caching primitives. They are also tightly coupled to the deployment model. The unstable_cache API and revalidateTag work well on Vercel. On a self-hosted Node.js server, the behavior is less predictable. On a multi-instance deployment, in-memory caches diverge immediately.

The deeper problem is that most caching implementations choose either simplicity, a single in-memory map, or power, Redis configured manually per use case. There is rarely a middle layer that handles the transition between them.

The solution

createCache returns a function that wraps any async operation with configurable caching behavior. Layers are provided as an ordered array, fastest first.

const cache = createCache({
  layers: [
    new MemoryStore(200),                          // L1: in-process LRU
    new RedisStore(new Redis(env.REDIS_URL)),       // L2: distributed
  ],
  defaultTtl: 3600,
});

export const getUser = cache(
  async (id: string) => db.user.findUnique({ where: { id } }),
  { tags: (id) => [`user:${id}`, "users"], ttl: 300 },
);

On a cache miss, the source function is called. The result propagates to all layers. On a cache hit in L2, the result is back-filled to L1 so the next request for the same key is served from memory, without a Redis round-trip.

Tag-based invalidation works across all layers simultaneously. When a user is updated, a single call clears every cache entry associated with that user, regardless of which layer holds it:

await getUser.invalidateTag(`user:${userId}`);

Stampede protection is built in. When dozens of concurrent requests trigger a cache miss for the same key at the same time, a common scenario after a cache expiry under load, only one call to the source function is made. All other callers receive the same Promise and resolve together when the single fetch completes.

Stale-while-revalidate allows returning a cached value immediately, even if it is stale, while refreshing it in the background. The next request gets the fresh value with no latency penalty.

@nx-safe-suite/audit-log: Logging That Survives Compliance

The problem

Audit logging is the feature that gets added after the first compliance review, built hastily, and never quite right. The common failure modes are: logs that contain passwords or PII in plaintext, logs that block the main request thread because they write synchronously to a database, and logs in a format that neither humans nor machines can parse reliably.

The solution

createAuditLog returns a logger configured with transports, a service name, and a list of sensitive fields to mask. Every entry sent to audit.log() is enriched with a timestamp, service name, and default status, then masked, then dispatched to all transports in parallel.

export const audit = createAuditLog({
  serviceName: "my-saas",
  sensitiveFields: ["password", "ssn", "creditCard", "email"],
  silent: true, // transport failures never break the main request path
  transports: [
    new ConsoleTransport({ stream: "stdout" }),    // structured JSON to stdout
    new PrismaTransport({ model: db.auditLog }),   // persisted to DB
  ],
});

The PII masking is recursive and case-insensitive. It operates on a shallow clone so the original object is never mutated. A payload containing { email: "albert@example.com", name: "Albert" } arrives at the transport as { email: "[REDACTED]", name: "Albert" }.

Three transports ship with the package. ConsoleTransport writes newline-delimited JSON to stdout or stderr, compatible with any log aggregation pipeline that parses structured stdout. HttpTransport posts to a webhook endpoint with configurable retry logic and timeout. PrismaTransport writes to any Prisma model, with a mapEntry option to transform the entry shape to match your schema exactly.

The transport interface is two lines:

interface AuditTransport {
  send(entry: AuditEntry): Promise<void>;
}

Implement those two lines and any destination works: Axiom, Datadog, Loki, a custom HTTP sink.

The Numbers

Package	Tests	Bundle (ESM)	Peer deps
`@nx-safe-suite/env`	11	~3KB	zod
`@nx-safe-suite/api-response`	27	~3KB	none
`@nx-safe-suite/route-guard`	31	~6KB	zod, jose (optional)
`@nx-safe-suite/server-cache`	22	~5KB	none
`@nx-safe-suite/audit-log`	24	~5KB	none

115 tests total. All passing. Strict TypeScript throughout.

A Note on What This Demonstrates

If you are reading this as someone evaluating my engineering judgment rather than as someone looking to use these packages, here is what I would point to.

The decision to make transport errors non-fatal by default in audit-log via silent: true reflects an understanding of production priorities: a logging failure should never degrade the user experience.

The decision to use Promise deduplication in server-cache rather than a lock reflects an understanding of the Node.js event loop: locks are unnecessary when you can share the Promise itself.

The decision to validate client variable prefixes eagerly in env, before schema validation runs, reflects an understanding of where configuration mistakes come from: the schema definition, not the environment values.

These are not clever tricks. They are the kind of decisions that come from having debugged the failure modes they prevent.

I Built Five npm Packages to Solve the Five Problems Every Next.js Backend Ignores

adeutou — Wed, 12 Aug 2026 11:48:00 +0000

A production-grade toolkit for Next.js backends, and the architectural thinking behind it.

After years of building internal tools and SaaS products with Next.js, I kept copying the same five things across every project. Not because they were hard to write, but because no one had packaged them together in a way that was coherent, composable, and genuinely production-ready.

So I built nx-safe-suite: a monorepo of five independently installable TypeScript packages that handle the foundational concerns of any serious Next.js backend.

This article covers the architecture and the reasoning. The next one goes deep on each package.

The Problem With "Just Use process.env"

Every Next.js tutorial ends the same way: process.env.DATABASE_URL. No validation. No type safety. No guarantee that the variable exists.

In production, this means one of two things happens. Either you catch the error immediately as a hard crash at startup, or worse, you do not. The variable is undefined, it flows silently through your application, and something breaks three layers deep in a way that takes an hour to trace back to its source.

This is not a Next.js problem. It is a discipline problem. And it is exactly the kind of problem that a well-designed package should eliminate at the boundary, not paper over with optional chaining and defensive null checks scattered throughout the codebase.

The same pattern repeats for error responses, authentication, caching, and audit logging. Every team solves them. Almost no team solves them consistently.

What nx-safe-suite Is

Five packages. Five problems. Each one installable on its own.

Package	Problem it solves
`@nx-safe-suite/env`	Environment variables that are validated, typed, and fail loudly
`@nx-safe-suite/api-response`	API responses that are consistent, RFC-compliant, and predictable
`@nx-safe-suite/route-guard`	Authentication, authorization, and validation without boilerplate
`@nx-safe-suite/server-cache`	Multi-tier caching with invalidation that actually works
`@nx-safe-suite/audit-log`	Structured audit logging that survives compliance reviews

They compose naturally. None of them requires the others. You can adopt one this week and the rest over the following months.

The Architecture Decision: Why Not a Framework?

The obvious alternative was a framework: a single opinionated abstraction that wraps all five concerns. I chose not to build one, and the reason is worth explaining.

Frameworks impose a contract. When you adopt a framework, you adopt its assumptions about your data model, your auth strategy, your deployment target. Those assumptions are often correct for the common case and deeply wrong for your specific case.

Individual composable packages impose an interface. They define what goes in and what comes out. You decide what happens in between.

This distinction matters at scale. When a framework assumption breaks down, and it always eventually does, you are refactoring across the entire abstraction. When a package interface breaks down, you swap the package.

The Monorepo Structure

All five packages live in a single repository, managed with pnpm workspaces and Turborepo.

nx-safe-suite/
├── packages/
│   ├── env/
│   ├── api-response/
│   ├── route-guard/
│   ├── server-cache/
│   └── audit-log/
└── apps/
    └── docs/

Turborepo handles the build graph. When route-guard depends on the error shape from api-response, Turborepo ensures the latter is always built first. The cache means that on a clean run, only changed packages rebuild. A build that would take 22 seconds takes 43 milliseconds on the second pass.

Versioning and publishing are handled by Changesets. Each meaningful change includes a changeset file describing the impact as patch, minor, or major. The release workflow on GitHub Actions assembles those into version bumps and publishes to npm automatically when merged to main.

The Dependency Philosophy

The five packages collectively have zero mandatory runtime dependencies on third-party libraries. Every dependency that exists is either a devDependency (TypeScript, Vitest, tsup) or a peerDependency that the consuming project almost certainly already has.

@nx-safe-suite/env lists zod as a peer. You bring your own Zod.

@nx-safe-suite/route-guard lists both zod and jose as peers. The jose dependency is optional and only needed if you use the built-in JWT verification mode.

The rest have nothing.

This matters for two reasons. First, it avoids version conflicts: you do not end up with two copies of Zod at different versions in your bundle. Second, it keeps the surface area honest. These packages solve specific structural problems. They do not replace your existing toolchain.

Quality Signals

Every package ships with a full test suite written in Vitest. The numbers across the five packages: 115 unit tests, all passing, covering success paths, failure paths, edge cases, and integration behavior between layers.

The TypeScript configuration is strict throughout: strict: true, noUncheckedIndexedAccess: true, noImplicitOverride: true. These are not cosmetic. They are the settings that catch the bugs TypeScript is designed to catch.

The CI pipeline runs on Node 20, 22, and 24. Packages that produce CJS and ESM builds are tested against both module systems.

The Library Mindset

Building a library forces a different kind of thinking than building an application. An application can tolerate internal inconsistency. A library cannot, because its surface area is a contract with every developer who installs it. Every public type, every default value, every error message is a decision that has consequences for someone else's code.

The decisions visible in nx-safe-suite are not incidental. The pluggable interfaces, the peer dependency choices, the RFC 9457 compliance, the Changesets workflow, the sub-42ms Turborepo cache hit: all of them reflect a specific way of thinking about software. Constraints are features. Composability beats comprehensiveness. A well-designed system makes the wrong thing hard to do by default.

Where to Find It

The code is public: github.com/adeutou/nx-safe-suite

The documentation is live at: adeutou.github.io/nx-safe-suite

The packages are on npm under the @nx-safe-suite scope.

The next article goes into each package individually: the problem it solves, the API design, and the implementation choices that are not obvious from the README.

Electricity Planning Engine, part 2: A Reader Comment Found a Real Gap in My Test Suite (and How I Fixed It)

adeutou — Mon, 27 Jul 2026 00:17:12 +0000

I wrote about the Electricity Planning Engine a little while back, including a timezone bug that made a correct price look "not found" after a database round trip. A few days later, Alex Shev left this comment:

Timezone bugs are brutal in planning engines because the result can look mathematically correct while being operationally wrong. Energy workflows especially need tests around boundaries, not just averages.

That is a genuinely sharp way to put it, and it is not just a comment about the bug I already wrote about. It is a comment about how I test the project in general, and I did not like how well it applied once I went and checked.

The part that stung a little

"Looks mathematically correct while being operationally wrong" is exactly what the original timezone bug was. PriceSeries::priceAt() threw a clean "price not found" error, which is arguably the good version of that failure mode: loud, easy to catch, hard to ship. A quieter version of the same class of mistake, off by one hour instead of missing entirely, would not throw anything. It would just return a plan that looks completely reasonable and is wrong the entire time it runs.

Alex's second point, boundaries over averages, is the one I actually had to go check rather than just agree with in the abstract. So I opened tests/Unit/Domain/Contract/PricingStrategyTest.php and looked at every hour used in every peak/off-peak assertion:

new DateTimeImmutable('2026-07-18 14:00:00') // peak
new DateTimeImmutable('2026-07-18 23:00:00') // off-peak
new DateTimeImmutable('2026-07-18 05:00:00') // off-peak

14:00, 23:00, 05:00. Every single one comfortably inside its window. None of them anywhere near the actual transition. The off-peak slot in the config is 22:00 to 06:00, and the comparison behind that lives in TimeSlot::contains():

// wraparound slot, e.g. 22:00 -> 06:00
return $minuteOfDay >= $this->startMinuteOfDay || $minuteOfDay < $this->endMinuteOfDay;

That >= versus < is exactly the kind of one-character decision that determines whether 22:00:00 itself is off-peak or not, and whether 06:00:00 itself is off-peak or already peak again. Nothing in the suite exercised either instant. A boundary mistake here would not crash, would not warn, would just silently bill one hour a day at the wrong rate, forever, until someone happened to notice their bill looked slightly off. That is Alex's point, precisely, and it was sitting in my own repo.

The fix

public function test_peak_off_peak_strategy_resolves_the_exact_boundary_minute_correctly(): void
{
    $strategy = PricingStrategyFactory::fromConfig(ContractType::PeakOffPeak, [
        'off_peak_slots' => [['start' => '22:00', 'end' => '06:00']],
        'seasons' => [[
            'label' => 'year_round',
            'months' => range(1, 12),
            'rates' => [
                ['slot' => 'peak', 'price_per_kwh' => 0.27],
                ['slot' => 'off_peak', 'price_per_kwh' => 0.20],
            ],
        ]],
    ]);

    // Just before the off-peak window opens: still peak.
    self::assertTrue($strategy->priceForHour(new DateTimeImmutable('2026-07-18 21:59:00'))->equals(Money::of(0.27)));
    // The window opens exactly at 22:00:00: start is inclusive.
    self::assertTrue($strategy->priceForHour(new DateTimeImmutable('2026-07-18 22:00:00'))->equals(Money::of(0.20)));
    // Just before the off-peak window closes: still off-peak.
    self::assertTrue($strategy->priceForHour(new DateTimeImmutable('2026-07-19 05:59:00'))->equals(Money::of(0.20)));
    // The window closes exactly at 06:00:00: end is exclusive, already peak.
    self::assertTrue($strategy->priceForHour(new DateTimeImmutable('2026-07-19 06:00:00'))->equals(Money::of(0.27)));
}

Four instants instead of three comfortable ones: one minute before the window opens, the exact opening second, one minute before it closes, the exact closing second. That is the whole idea of testing boundaries instead of averages, written down as assertions instead of just agreed with in a comment thread.

Proving the test actually tests something

A boundary test that would pass against a broken implementation is worse than no test, it is a false sense of safety. So before trusting this one, I broke the code on purpose: flipped the wraparound comparison from >= / < to > / <=, one character each, and reran just this test.

It failed immediately, on the 22:00:00 assertion, exactly where it should:

Failed asserting that false is true.
at tests/Unit/Domain/Contract/PricingStrategyTest.php:73

Then I reverted the one-character change and ran the full suite: 104 tests, 752 assertions, green. That failure-then-pass cycle is the only way I trust a new test is doing its job rather than just decorating the file with more green checkmarks.

Thanks, Alex

None of this was a bug in production, it was a gap in coverage that a bug could have hidden in later. Comments like Alex's are exactly how that gap gets found before the bug does instead of after. If you have opinions on where else this project's tests are testing averages instead of edges, the repo is open, and so are the issues.

Electricity Planning Engine: An Hourly Arbitrage API for Batteries and Solar, Plus the Timezone Bug That Almost Broke It

adeutou — Wed, 22 Jul 2026 10:14:12 +0000

A grid that pays you to consume electricity is not a thought experiment. In Germany, wholesale power prices have gone negative often enough that it barely makes headlines anymore: on a windy, sunny afternoon, there is simply more electricity than the grid can absorb, and someone has to be paid to take it. Meanwhile, in most homes, none of that signal reaches the washing machine, the home battery, or the EV charger. They run on habit, not on price.

That gap between "electricity has an hourly price" and "almost nothing reacts to it" is what I set out to close, at a small scale, with the Electricity Planning Engine: a Laravel API that decides, hour by hour over a 24 to 72 hour horizon, whether a household should draw from the grid, charge or discharge a battery, or export solar surplus, based on its energy contract and the market price.

Full source is on GitHub: github.com/adeutou/electricity-planning-engine. This post walks through why the problem matters, then how the solution is actually built, with enough real code that you can follow along or lift pieces of it for your own project.

Why hourly prices are not a gimmick

Germany is the best possible example for this, because it is living the consequences of both extremes at once.

On the supply side, negative prices are not an anomaly, they are the visible symptom of an engineering problem: when solar and wind output exceeds demand, the grid has to either store the surplus, curtail it, or pay someone to consume it. Every megawatt-hour that gets curtailed is clean energy that was already generated and still got wasted, while a gas peaker plant somewhere ramps up a few hours later for the evening spike.

On the demand side, Germany has been pushing dynamic, hourly-priced tariffs into the mainstream, with providers like Tibber or aWATTar built entirely around the idea. Grid operators also already have mechanisms to throttle controllable devices like heat pumps and EV chargers during congestion, in exchange for reduced grid fees. The infrastructure for "your appliances should react to the grid" already exists. What is missing, in most homes, is the software that makes the decision.

And then there is Dunkelflaute, the German word for days with neither wind nor sun: an arbitrage engine cannot just chase cheap hours, it has to hold reserve for the peak it can see coming.

Building it: the domain first

I did not start with the arbitrage algorithm. I started with the domain, because if the domain model is wrong, the cleverest algorithm on top of it is still wrong. The rule I followed throughout: app/Domain never imports a single Laravel or Eloquent class. If you can use Illuminate\... in a file, it does not belong in the domain.

Contracts are strategies, not prices

An EnergyContract never computes its own price. It delegates to a PricingStrategyInterface:

interface PricingStrategyInterface
{
    public function priceForHour(DateTimeImmutable $hour, ?PriceSeries $marketPrices = null): Money;
}

$marketPrices is nullable and ignored by most implementations. Only a contract indexed on the wholesale market actually needs it, which is exactly the case a German Tibber-style dynamic tariff maps onto:

final class DynamicSpotPricingStrategy implements PricingStrategyInterface
{
    public function __construct(
        private readonly Money $supplierFeePerKwh,
        private readonly Percentage $supplierMargin,
    ) {}

    public function priceForHour(DateTimeImmutable $hour, ?PriceSeries $marketPrices = null): Money
    {
        if ($marketPrices === null) {
            throw DomainException::because(
                'DynamicSpotPricingStrategy requires market prices to compute a rate.'
            );
        }

        $wholesalePrice = $marketPrices->priceAt($hour);

        return $wholesalePrice
            ->multiply(1 + $this->supplierMargin->toFraction())
            ->add($this->supplierFeePerKwh);
    }
}

Three other strategies implement the same interface: a flat fixed rate, a peak/off-peak schedule with seasonal rates and daily time windows (midnight wraparound handled explicitly), and a colored-day tariff modeled after EDF's French Tempo scheme, where whole days get reclassified rather than fixed hourly windows. None of them know the others exist. The arbitrage engine only ever calls EnergyContract::priceForHour(), so adding a fifth strategy for a different market never touches the engine, the API, or the other three strategies.

A battery that refuses to lie about its own limits

The battery is the one piece of the domain where getting the physics slightly wrong would make every downstream decision wrong. It is an immutable entity: charge() and discharge() return a new instance rather than mutating state, which matters later when the advanced engine needs to reason about several possible futures without side effects.

public function charge(Energy $gridEnergyIn, float $hours = 1.0): self
{
    $limit = $this->maxChargeableEnergy($hours);

    if ($gridEnergyIn->isGreaterThan($limit)) {
        throw DomainException::because(
            "Cannot charge {$gridEnergyIn}: exceeds max chargeable energy of {$limit} for {$hours}h."
        );
    }

    $storedIncrease = $gridEnergyIn->multiply($this->chargeEfficiency());

    return $this->withSoc($this->soc->withLevel($this->soc->level()->add($storedIncrease)));
}

Two details worth calling out. First, chargeEfficiency() is sqrt($this->roundTripEfficiency), applied on both the charge and discharge side, so a 90% round-trip efficiency becomes roughly 94.9% on each leg rather than 90% twice, which is the standard way to model it without separate manufacturer figures for each direction. Second, exceeding a physical limit throws, it does not silently clamp. A caller that asks a battery to accept more energy than it has headroom for has a bug, and clamping the value would just hide it a few requests later.

Two engines, one lesson in greed

V1 is greedy, on purpose. For every hour: let solar cover consumption first, then decide what to do with whatever is left over.

foreach ($horizon->iterateHours() as $hourIndex => $hourStart) {
    $priceNow = $pricesByHour[$hourIndex];
    $pvProduction = $pv->productionAt($hourStart, $hourIndex);
    $demand = $consumption->consumptionAt($hourStart, $hourIndex);

    $consumptionFromPv = Energy::min($pvProduction, $demand);
    $surplus = $pvProduction->subtract($consumptionFromPv);
    $deficit = $demand->subtract($consumptionFromPv);

    if (! $surplus->isZero()) {
        // charge the battery if the price now beats the average of the
        // next few hours, otherwise export the surplus
        [$battery, $batteryCharge, $exportToGrid] = $this->handleSurplus(/* ... */);
    } elseif (! $deficit->isZero()) {
        // discharge if the price now beats the average of the past few
        // hours, otherwise pull from the grid
        [$battery, $batteryDischarge] = $this->handleDeficit(/* ... */);
    }

    // ... build the HourlyDecision for this hour and move on
}

It is simple, it is correct, and it has one specific weakness: a battery can get spent on an hour that only looks expensive relative to its immediate neighbors, and sit empty when the real daily peak shows up later, outside that local comparison window.

V2 fixes exactly that. Instead of comparing each hour to its local neighborhood, it ranks every hour in the whole horizon by price in a first pass, cheapest surplus hours and priciest deficit hours first, and accumulates until the battery's available headroom would be filled. That produces two global price thresholds. A second pass then replays the horizon hour by hour, gating charge and discharge decisions on those global thresholds instead of a rolling average.

I did not want to just assert V2 is smarter, so I wrote a test that proves it: a price series with a moderate bump early in the day, enough to trip V1's local rule, and the real peak much later. V1 spends its battery early and has nothing left for the real peak. V2 recognizes the later peak is the better opportunity and holds capacity for it. Total cost on that scenario: 12.5% lower with V2. Same battery, same prices, just a different notion of "when."

The bug that lied to me for a day

The most interesting bug in this project was not in the arbitrage logic. It was in a class that looked almost too simple to break: PriceSeries, which indexes hourly prices so the engine can look one up by timestamp.

The original version indexed points by an ISO-8601 string that included the UTC offset:

private function key(DateTimeImmutable $hour): string
{
    return $hour->format(DATE_ATOM); // e.g. "2026-07-18T14:00:00+02:00"
}

Two DateTimeImmutable instances representing the exact same instant, but constructed in different timezones, produce two different strings for that instant, and therefore two different keys. The first time I round-tripped a plan through PostgreSQL, this bit me for real: the contract was built in Europe/Berlin, the database returned everything in UTC, and a price that was unambiguously there suddenly came back as "not found."

The cause was subtle because nothing about it looked wrong locally. The contract logic was right. The database mapping was right. It was the equality check itself, hiding one layer below both of them, comparing string representations of time instead of the instant they represented. The fix:

private function key(DateTimeImmutable $hour): int
{
    return $hour->getTimestamp();
}

A Unix timestamp does not care what timezone produced it. I paired the fix with normalizing every timestamp to UTC at the Eloquent persistence boundary, and with a permanent regression test that constructs the same instant in two different timezones and asserts the lookup still succeeds, because this is exactly the kind of bug that comes back quietly if nothing is watching for it.

Try it yourself

git clone https://github.com/adeutou/electricity-planning-engine.git
cd electricity-planning-engine
docker compose up -d --build

That starts the API, PostgreSQL, and Redis. Then ask it to plan a day for a flat-rate contract with a 6 kWc solar system and a 10 kWh battery:

curl -X POST http://localhost:8000/api/simulate \
  -H "Content-Type: application/json" \
  -d '{
    "contract": {"country_code":"DE","zone":"DE","contract_type":"fixed","pricing_config":{"price_per_kwh":0.30}},
    "horizon": {"start":"2026-07-20T00:00:00+02:00","end":"2026-07-21T00:00:00+02:00"},
    "mode": "advanced",
    "pv": {"peak_power_kwc": 6},
    "battery": {"capacity_kwh": 10, "initial_soc_percent": 50}
  }'

The response includes an id. GET /api/plans/{id}/chart.svg renders the resulting plan as a chart, server-side, no JavaScript involved, straight in a browser tab.

The pipeline behind it

Every push runs the full test suite on PHP 8.2 and 8.3 (the range declared in composer.json) and validates the Docker build. Nothing gets published on an ordinary push, a release is a deliberate action:

on:
  push:
    tags:
      - 'v*.*.*'

permissions:
  contents: write   # create the GitHub Release
  packages: write   # publish to ghcr.io

jobs:
  tests:
    uses: ./.github/workflows/tests.yml

  publish-image:
    needs: tests
    # ... build and push ghcr.io/adeutou/electricity-planning-engine:<version>

  release:
    needs: publish-image
    # ... create the GitHub Release with generated notes

Pushing git tag v1.0.0 && git push origin v1.0.0 is the only thing that triggers a publish. Everything else, every ordinary commit, only has to prove it still builds and passes.

Why this matters beyond the demo

This project is a technical demonstration, but the problem underneath it is not a toy one. As more homes add solar panels, batteries, and EVs, and as the grid leans harder into intermittent generation, "when should this device consume, store, or sell" stops being a nice-to-have and becomes both a household economics question and a grid stability one. Germany is not a special case here, it is just further along the curve, which makes it the clearest place to see what everyone else is heading toward.

Writing this kind of decision logic properly, with a domain model that actually holds up and algorithms whose behavior you can prove with a test instead of just hoping for, is exactly the kind of backend engineering work I want to keep doing.

Source, tests, and the full architecture write-up: GitHub. MIT licensed, issues and forks welcome.

Self-Hosting Like a Pro, Part 4: Monitoring with Prometheus, Grafana and Loki, plus a CI/CD Pipeline That Actually Works

adeutou — Wed, 22 Jul 2026 03:55:20 +0000

The stack from Part 3 is live: multiple domains, isolated namespaces, TLS everywhere. But a production system you cannot observe is a production system you do not control. In this part we install a full observability stack on a modest 2 vCPU, 8 GB VPS, then wire up a GitHub Actions pipeline so that a git push becomes a deployment. Both came with surprises. I will share all of them.

The monitoring stack and its budget

The classic trio:

Prometheus scrapes and stores metrics from every pod and from the node itself
Grafana turns those metrics into dashboards
Loki with Promtail aggregates logs from every container in the cluster

On a small VPS the default Helm values of these charts will eat your memory alive. Here is the budget that works for me, about 1.2 GB total for the whole namespace:

prometheus:
  prometheusSpec:
    retention: 15d
    retentionSize: "8GB"
    resources:
      requests:
        cpu: 100m
        memory: 256Mi
      limits:
        cpu: 500m
        memory: 512Mi

Retention matters more than people think. Fifteen days of metrics on an 8 GB size cap keeps the disk predictable on a 100 GB volume. For logs, seven days is plenty for a personal infrastructure:

loki:
  config:
    limits_config:
      retention_period: 168h
    compactor:
      retention_enabled: true

One K3s specific detail: disable the components that do not exist on a lightweight distribution, otherwise Prometheus fills up with permanently failing targets:

kubeEtcd:
  enabled: false
kubeControllerManager:
  enabled: false
kubeScheduler:
  enabled: false
kubeProxy:
  enabled: false

Three installation traps on K3s

The Helm install of kube-prometheus-stack failed for me three times, each for a different reason. Documenting them here so you skip the debugging session.

Trap one: the admission webhook job hangs. The chart runs a pre install job that generates TLS certificates for its admission webhooks. On my cluster that job ran for nineteen minutes without finishing and blocked everything behind a "timed out waiting for the condition" error. On a single node personal cluster the admission webhooks are dispensable. Disable them:

helm install monitoring prometheus-community/kube-prometheus-stack \
  --namespace ns-monitoring \
  --values monitoring-values.yaml \
  --set prometheusOperator.admissionWebhooks.enabled=false \
  --set prometheusOperator.admissionWebhooks.patch.enabled=false \
  --set prometheusOperator.tls.enabled=false

Trap two: half measures crash loop. My first attempt disabled the webhook job but not the TLS mount that depended on it. The operator pod then crash looped on a missing secret called monitoring-kube-prometheus-admission. If you disable the webhooks, disable the TLS block too. And if the release ends up in a broken state, uninstall it cleanly and reinstall rather than patching a corpse.

Trap three: quotas versus third party charts. This is the lesson from Part 3 striking again. My ResourceQuota on the monitoring namespace required every container to declare resources, but the Grafana chart ships init containers without any. Result: zero pods, zero error messages at the Deployment level, and the real reason buried in the ReplicaSet events:

Error creating: pods "monitoring-grafana-..." is forbidden:
failed quota: must specify limits.cpu for: init-chown-data, ...

The pragmatic fix on a personal cluster is to drop the quota on the monitoring namespace. The purist fix is to override the resources of every sub chart container. I chose pragmatism.

The general debugging rule that emerged: when a Deployment shows desired pods but zero current pods, run kubectl describe on the ReplicaSet. Quota rejections live there and nowhere else.

Exposing Grafana safely

Grafana lives on its own subdomain behind Traefik, with two layers of authentication: a basic auth middleware at the proxy level, then the Grafana login itself.

apiVersion: traefik.io/v1alpha1
kind: Middleware
metadata:
  name: grafana-auth
  namespace: ns-monitoring
spec:
  basicAuth:
    secret: grafana-basic-auth

Generate the htpasswd value, base64 encode it, store it in a Secret, reference it from the middleware. Two minutes of work for a serious reduction of exposed attack surface on a service that holds every metric of your infrastructure.

With Loki registered as a Grafana datasource, the payoff is immediate: one interface where you can jump from a CPU spike on a dashboard straight to the logs of the pod that caused it.

The CI/CD pipeline

Manual deployment was fine while building. It stops being fine the third time you type the same six commands. The target workflow:

git push main
  detect which apps changed
  lint and test only those apps
  build Docker images, push to GitHub Container Registry
  SSH into the VPS, update the image, wait for the rollout

Path filtering keeps the pipeline fast in a monorepo. Touching only the frontend must not rebuild the blog image:

- uses: dorny/paths-filter@v3
  with:
    filters: |
      web:
        - 'apps/web/**'
      worker:
        - 'apps/crosspost-worker/**'

Images are tagged twice, latest and the short commit SHA. The SHA tag is your rollback button: redeploying any previous version is one kubectl set image away.

Five pipeline failures and their fixes

My pipeline went red five times before going green. Every failure was a lesson.

Failure one: pnpm version conflict. The package.json declared a packageManager field while the workflow pinned a version on the pnpm setup action. The action refuses ambiguity and aborts. Fix: remove the version from the workflow and let packageManager be the single source of truth.

Failure two: module level SDK instantiation. The contact route created its Resend client at import time. Next.js executes route modules while collecting page data during the build, where no API key exists, so the build crashed. Fix: lazy initialization.

let client: Resend | null = null;
function getClient(): Resend {
  if (!client) client = new Resend(process.env.RESEND_API_KEY);
  return client;
}

The wider rule: never instantiate SDK clients at module scope in a Next.js app. Always create them inside the request handler path.

Failure three: wrong Docker build context. In a monorepo the lockfile lives at the root. Building with the app folder as context means the Dockerfile cannot copy it. The build must run from the repository root with the Dockerfile referenced by path, and the standalone output of Next.js lands in a nested folder, which changes the runtime paths too:

COPY --from=builder /app/apps/web/.next/standalone ./
COPY --from=builder /app/apps/web/.next/static ./apps/web/.next/static
CMD ["node", "apps/web/server.js"]

Failure four: registry permissions. The first image push was done manually with a personal access token, which made me the package owner. The automatic GITHUB_TOKEN of the workflow then received a 403 on push. Fix: in the package settings on GitHub, grant the repository write access under Manage Actions access. One click per package, easy to forget, guaranteed 403 if you do.

Failure five: a corrupted SSH secret. The deploy step failed with "error in libcrypto", which is OpenSSH speak for "this private key file is malformed". The key had been copied by hand into the GitHub secret and lost its line breaks along the way. Fix: pipe the file straight into the clipboard and paste it without touching it. On Windows:

Get-Content "$env:USERPROFILE\.ssh\deploy_key" -Raw | Set-Clipboard

The bonus bug: a page frozen in time

With the pipeline green, one ghost remained. The portfolio kept showing placeholder articles even though the blog API returned the real ones. Environment variables were correct inside the pod. Fetching from inside the pod worked. No errors anywhere.

The cause was subtle. The articles component guards its fetch: if the Ghost credentials are missing, it returns demo content without fetching. During the Docker build no credentials exist, so no fetch ran during prerendering. And Next.js only marks a page as revalidating if it actually observes a fetch with a revalidate option during the build. No fetch observed means fully static page, cached forever, never regenerated. My revalidate option inside the fetch call was correct and completely unused.

The fix is one line at the route level, which forces incremental static regeneration regardless of what happens during the build:

export const revalidate = 300;

After the next deployment, the first visit still serves the stale page but triggers regeneration in the background, and the second visit shows real data. Every future article now appears on the portfolio within five minutes, no redeploy needed.

Where we stand

The infrastructure is now complete:

Full metrics and log visibility through Grafana on a protected subdomain
Alerting foundation in place with Alertmanager
A pipeline where git push main lints, tests, builds, publishes and deploys only what changed
Rollback to any previous version in one command thanks to SHA tagged images

The whole system, applications and observability included, runs within 8 GB of RAM on a single VPS. Self hosting like a pro is not about big hardware. It is about isolation, budgets, and automating yourself out of the deployment loop.

Next up: backups and disaster recovery, because an infrastructure you cannot restore is an infrastructure you do not own.

Self-Hosting Like a Pro, Part 2: Docker, K3s and Traefik v3 with Automatic HTTPS

adeutou — Wed, 22 Jul 2026 02:47:16 +0000

This is Part 2 of a four-part series where I document how I turned a 10€/month VPS into a production-grade platform hosting multiple projects. In Part 1 we hardened a fresh Ubuntu server. Today we install the actual platform: a container runtime, a lightweight Kubernetes distribution, a modern reverse proxy, and automatic TLS certificates. By the end of this article, deploying an app with HTTPS will take one YAML file and zero manual certificate handling.*

Why Kubernetes on a single VPS?

Fair question. Docker Compose would work, and for a single project I would recommend it without hesitation. But my server hosts several unrelated projects: a portfolio blog, a university group website, and a SaaS platform. I want:

Isolation: a memory leak in one project must not take down the others.
Resource quotas: each project gets a defined slice of the 8 GB RAM, enforced by the platform, not by hope.
Declarative deployments: the entire infrastructure lives in Git as YAML. If the server burns down, I can rebuild it in an hour.
One ingress to rule them all: a single reverse proxy routes all domains and handles all certificates.

Full Kubernetes (kubeadm) would eat half the server's resources just to run itself. K3s is a certified Kubernetes distribution by SUSE that fits in a ~512 MB memory footprint. Same API, same YAML, a fraction of the overhead. It is the sweet spot for a single-node setup.

What you need

The hardened Ubuntu VPS from Part 1 (2 vCPU / 8 GB RAM or more recommended)
A domain name with DNS you control
45 minutes

Before starting, create a DNS A record pointing a test subdomain to your server, for example:

whoami.yourdomain.com  →  YOUR_SERVER_IP

DNS propagation can take a few minutes, so doing it now means it will be ready when we need it in Step 6.

Step 1: Install Docker

K3s uses its own container runtime (containerd), so strictly speaking Docker is not required to run the cluster. We install it anyway, because it is invaluable for building images locally on the server and for quick debugging.

Use the official convenience script:

curl -fsSL https://get.docker.com | sudo sh

Add your user to the docker group so you can run it without sudo:

sudo usermod -aG docker $USER
newgrp docker

Verify:

docker run --rm hello-world

One important detail on a hardened server: Docker manipulates iptables directly and can bypass UFW rules when you publish ports with -p. Since all our public traffic will go through K3s and Traefik, avoid publishing Docker ports on this machine. If you ever need a quick test container, bind it to localhost only: -p 127.0.0.1:8080:80.

Step 2: Install K3s

One command, about thirty seconds:

curl -sfL https://get.k3s.io | sh -s - \
  --disable traefik \
  --write-kubeconfig-mode 644

Two flags deserve an explanation:

--disable traefik: K3s bundles Traefik, but we want to install and control our own Traefik v3 via Helm, with our own configuration. Letting K3s manage it means fighting its defaults later.
--write-kubeconfig-mode 644: makes the kubeconfig readable by non-root users, convenient on a single-user server. On a shared machine, skip this flag and copy the kubeconfig to your user manually.

Check that the node is ready:

kubectl get nodes

Expected output:

NAME        STATUS   ROLES                  AGE   VERSION
srv-xxxxx   Ready    control-plane,master   30s   v1.33.x+k3s1

Make kubectl work in every session by pointing it at the K3s kubeconfig:

echo 'export KUBECONFIG=/etc/rancher/k3s/k3s.yaml' >> ~/.bashrc
source ~/.bashrc

Step 3: Install Helm

Helm is the package manager for Kubernetes. We will use it to install Traefik and cert-manager with pinned, reproducible configurations.

curl https://raw.githubusercontent.com/helm/helm/main/scripts/get-helm-3 | bash
helm version

Step 4: Install Traefik v3

Traefik is our front door: it receives all HTTP/HTTPS traffic on ports 80 and 443, routes requests to the right application based on the domain name, and terminates TLS.

Add the official Helm repository:

helm repo add traefik https://traefik.github.io/charts
helm repo update

Create a values file so the configuration lives in Git, not in your shell history:

mkdir -p ~/infra/traefik && nano ~/infra/traefik/values.yaml

# ~/infra/traefik/values.yaml
deployment:
  kind: Deployment
  replicas: 1

service:
  type: LoadBalancer   # K3s ships with ServiceLB (Klipper), this binds ports 80/443 on the node

ports:
  web:
    port: 8000
    exposedPort: 80
    redirections:
      entryPoint:
        to: websecure
        scheme: https
        permanent: true
  websecure:
    port: 8443
    exposedPort: 443
    tls:
      enabled: true

providers:
  kubernetesCRD:
    enabled: true
  kubernetesIngress:
    enabled: true

logs:
  general:
    level: INFO
  access:
    enabled: true

resources:
  requests:
    cpu: 100m
    memory: 128Mi
  limits:
    memory: 256Mi

The redirections block is doing quiet but important work: every HTTP request is permanently redirected to HTTPS at the entrypoint level, so no application ever needs to think about it.

Install into its own namespace:

kubectl create namespace traefik
helm install traefik traefik/traefik \
  --namespace traefik \
  --values ~/infra/traefik/values.yaml

Verify the pod is running and the ports are bound:

kubectl get pods -n traefik
kubectl get svc -n traefik

The service should show EXTERNAL-IP equal to your server's IP, with ports 80 and 443 mapped. At this point, visiting http://YOUR_SERVER_IP returns a 404 from Traefik — which is perfect: the front door is open, there is just nothing behind it yet.

Step 5: Install cert-manager

cert-manager automates the entire Let's Encrypt lifecycle: it requests certificates, answers the ACME challenges, stores the certs as Kubernetes secrets and renews them before expiry. Set it up once, never think about TLS again.

helm repo add jetstack https://charts.jetstack.io
helm repo update

helm install cert-manager jetstack/cert-manager \
  --namespace cert-manager \
  --create-namespace \
  --set crds.enabled=true

Wait for the three pods to be ready:

kubectl get pods -n cert-manager

Now define two ClusterIssuers: one for Let's Encrypt staging, one for production. Always test with staging first, because the production endpoint rate-limits you to 5 failed attempts per hour, and debugging DNS issues while rate-limited is a special kind of misery.

mkdir -p ~/infra/cert-manager && nano ~/infra/cert-manager/cluster-issuers.yaml

apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-staging
spec:
  acme:
    server: https://acme-staging-v02.api.letsencrypt.org/directory
    email: you@yourdomain.com
    privateKeySecretRef:
      name: letsencrypt-staging-key
    solvers:
      - http01:
          ingress:
            class: traefik
---
apiVersion: cert-manager.io/v1
kind: ClusterIssuer
metadata:
  name: letsencrypt-prod
spec:
  acme:
    server: https://acme-v02.api.letsencrypt.org/directory
    email: you@yourdomain.com
    privateKeySecretRef:
      name: letsencrypt-prod-key
    solvers:
      - http01:
          ingress:
            class: traefik

Replace the email (Let's Encrypt uses it for expiry warnings) and apply:

kubectl apply -f ~/infra/cert-manager/cluster-issuers.yaml
kubectl get clusterissuers

Both issuers should show READY: True after a few seconds.

Step 6: Deploy a test app with automatic HTTPS

Time for the payoff. We deploy whoami, a tiny web server that echoes request information, and expose it over HTTPS on the subdomain you configured earlier.

mkdir -p ~/infra/apps && nano ~/infra/apps/whoami.yaml

apiVersion: v1
kind: Namespace
metadata:
  name: ns-test
---
apiVersion: apps/v1
kind: Deployment
metadata:
  name: whoami
  namespace: ns-test
spec:
  replicas: 1
  selector:
    matchLabels:
      app: whoami
  template:
    metadata:
      labels:
        app: whoami
    spec:
      containers:
        - name: whoami
          image: traefik/whoami:latest
          ports:
            - containerPort: 80
          resources:
            requests:
              cpu: 10m
              memory: 16Mi
            limits:
              memory: 32Mi
---
apiVersion: v1
kind: Service
metadata:
  name: whoami-svc
  namespace: ns-test
spec:
  selector:
    app: whoami
  ports:
    - port: 80
      targetPort: 80
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: whoami-cert
  namespace: ns-test
spec:
  secretName: whoami-tls
  issuerRef:
    name: letsencrypt-prod
    kind: ClusterIssuer
  dnsNames:
    - whoami.yourdomain.com
---
apiVersion: traefik.io/v1alpha1
kind: IngressRoute
metadata:
  name: whoami-route
  namespace: ns-test
spec:
  entryPoints:
    - websecure
  routes:
    - match: Host(`whoami.yourdomain.com`)
      kind: Rule
      services:
        - name: whoami-svc
          port: 80
  tls:
    secretName: whoami-tls

Replace whoami.yourdomain.com with your actual subdomain (twice), then:

kubectl apply -f ~/infra/apps/whoami.yaml

Watch the certificate being issued:

kubectl get certificate -n ns-test -w

Within a minute, READY flips to True. Now open https://whoami.yourdomain.com in your browser: a valid Let's Encrypt certificate, automatic HTTP→HTTPS redirect, and the whoami output showing your request went through Traefik.

Take a second to appreciate what just happened: you wrote one YAML file, and the platform handled deployment, routing, certificate issuance and TLS termination. Every future application follows the exact same pattern.

If the certificate stays stuck in READY: False, the usual suspects are:

# Check the ACME challenge status
kubectl describe certificaterequest -n ns-test
kubectl get challenges -n ns-test

Nine times out of ten it is DNS: the A record has not propagated yet, or points to the wrong IP. Verify with dig whoami.yourdomain.com +short.

Final checklist

# 1. K3s node ready
kubectl get nodes
# Expected: STATUS Ready

# 2. Traefik running and bound to 80/443
kubectl get svc -n traefik
# Expected: EXTERNAL-IP = your server IP, ports 80/443

# 3. ClusterIssuers ready
kubectl get clusterissuers
# Expected: both READY True

# 4. Test app serving valid HTTPS
curl -sI https://whoami.yourdomain.com | head -1
# Expected: HTTP/2 200

# 5. HTTP redirects to HTTPS
curl -sI http://whoami.yourdomain.com | grep -i location
# Expected: location: https://whoami.yourdomain.com/

Once everything passes, clean up the test app if you like:

kubectl delete -f ~/infra/apps/whoami.yaml

What's next

We now have a hardened server running a Kubernetes platform with automatic HTTPS. In Part 3, we make it truly multi-tenant: one namespace per project with enforced resource quotas, a shared PostgreSQL and Redis for the small projects, and Traefik middlewares for security headers, rate limiting and CORS. That is where the "several unrelated projects on one 8 GB server without them stepping on each other" promise gets fulfilled.

Questions or suggestions? Reach out, I answer everything. If your certificate refuses to issue and you have already sacrificed a rubber duck to the DNS gods, send me the output of kubectl get challenges and we will figure it out.

Self-Hosting Like a Pro, Part 1: Hardening a Fresh Ubuntu VPS

adeutou — Mon, 06 Jul 2026 09:26:36 +0000

This is the first article in a four-part series where I document how I turned a 10€/month VPS into a production-grade platform hosting my portfolio, a university group webapplication and a SaaS product, all isolated from each other with Kubernetes. In this part, we take a fresh Ubuntu server and lock it down properly before installing anything else.

Why bother with hardening?

The moment your VPS gets a public IP address, it starts receiving attacks. Not "might receive", it starts. Within minutes, automated bots will probe port 22, try root:root, admin:admin123 and thousands of other credential combinations. If you skip this step and jump straight to deploying your apps, you are building on sand.

The good news: an hour of work is enough to eliminate the vast majority of these threats. Here is what we will set up:

A non-root user with sudo privileges
SSH key authentication, with passwords and root login disabled
UFW as a simple, effective firewall
Fail2ban to ban brute-force attackers automatically
Automatic security updates

What you need

A fresh VPS running Ubuntu 24.04 LTS or newer. I use a Hostinger KVM 2 (2 vCPU, 8 GB RAM, 100 GB NVMe), but any provider works: Hetzner, DigitalOcean, OVH, Contabo.
The root password or SSH key your provider gave you.
A terminal on your local machine (macOS, Linux, or WSL on Windows).

Throughout this tutorial, replace YOUR_SERVER_IP with your server's IP address and deploy with the username you want to use.

Step 1: First login and system update

Connect as root for the first and last time:

ssh root@YOUR_SERVER_IP

Update everything before touching anything else:

apt update && apt upgrade -y
apt autoremove -y

If a kernel update was installed, reboot now:

reboot

Wait a minute, then reconnect.

Step 2: Create a non-root user

Working as root is like driving without a seatbelt: fine until it isn't. One mistyped rm -rf and the party is over. Create a dedicated user:

adduser deploy

Choose a strong password (you will still need it for sudo, even after we disable password SSH logins). Then grant sudo privileges:

usermod -aG sudo deploy

Verify it works:

su - deploy
sudo whoami
# Expected output: root

Step 3: SSH key authentication

Passwords can be brute-forced. SSH keys, in practice, cannot. If you don't have a key pair yet, generate one on your local machine (not on the server):

ssh-keygen -t ed25519 -C "deploy@YOUR_SERVER_IP"

Ed25519 is the modern default: shorter keys, faster, and at least as secure as 4096-bit RSA.

Now copy the public key to the server:

ssh-copy-id deploy@YOUR_SERVER_IP

Test it from your local machine:

ssh deploy@YOUR_SERVER_IP

If you log in without being asked for a password, the key works. Do not proceed to the next step until this works, otherwise you will lock yourself out.

Step 4: Harden the SSH daemon

Now we disable everything an attacker could exploit. Open the SSH configuration:

sudo nano /etc/ssh/sshd_config

Find and change (or add) the following lines:

PermitRootLogin no
PasswordAuthentication no
PubkeyAuthentication yes
MaxAuthTries 3
ClientAliveInterval 300
ClientAliveCountMax 2
X11Forwarding no

A quick explanation of each:

PermitRootLogin no: root can no longer log in over SSH at all. Attackers love the root account because they don't need to guess the username.
PasswordAuthentication no: keys only. Brute-force attacks become pointless.
MaxAuthTries 3: three failed attempts and the connection is dropped.
ClientAliveInterval / ClientAliveCountMax: idle sessions are closed after 10 minutes.
X11Forwarding no: we are running a server, not a remote desktop.

On Ubuntu 24.04+, also check the drop-in directory, because cloud providers often override settings there:

ls /etc/ssh/sshd_config.d/

If you see a file like 50-cloud-init.conf containing PasswordAuthentication yes, edit or remove it, otherwise it silently wins over your main config.

Validate the configuration and restart the daemon:

sudo sshd -t
sudo systemctl restart ssh

Keep your current session open and test the new rules from a second terminal:

ssh deploy@YOUR_SERVER_IP        # should work (key)
ssh root@YOUR_SERVER_IP          # should be refused

Step 5: Firewall with UFW

UFW (Uncomplicated Firewall) lives up to its name. The strategy is simple: deny everything inbound, then open only what we need.

sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp    # HTTP
sudo ufw allow 443/tcp   # HTTPS

The order matters: allow OpenSSH before enabling the firewall, or you will cut the branch you are sitting on. Then:

sudo ufw enable
sudo ufw status verbose

Expected output:

Status: active
Default: deny (incoming), allow (outgoing), disabled (routed)

To                         Action      From
--                         ------      ----
OpenSSH                    ALLOW IN    Anywhere
80/tcp                     ALLOW IN    Anywhere
443/tcp                    ALLOW IN    Anywhere

That's it. Ports 80 and 443 will later be handled by our reverse proxy (Traefik, in Part 2). Everything else, including databases, monitoring dashboards and internal services, stays invisible from the internet.

Step 6: Fail2ban

Even with keys-only authentication, bots will keep hammering your SSH port and polluting your logs. Fail2ban watches the logs and bans IPs that misbehave.

sudo apt install fail2ban -y

Never edit jail.conf directly (it gets overwritten on updates). Create a local override instead:

sudo nano /etc/fail2ban/jail.local

[DEFAULT]
bantime  = 1h
findtime = 10m
maxretry = 5

[sshd]
enabled = true
bantime = 24h
maxretry = 3

Translation: any IP that fails SSH authentication 3 times within 10 minutes is banned for 24 hours. Enable and start the service:

sudo systemctl enable fail2ban
sudo systemctl restart fail2ban

Check that the SSH jail is active:

sudo fail2ban-client status sshd

Come back after a day and run that command again. Seeing the list of banned IPs grow is oddly satisfying, and a good reminder of why this whole article exists.

Step 7: Automatic security updates

A hardened server that runs unpatched software is only hardened on paper. Ubuntu's unattended-upgrades installs security patches automatically:

sudo apt install unattended-upgrades -y
sudo dpkg-reconfigure -plow unattended-upgrades

Select "Yes" in the dialog. To verify the configuration:

cat /etc/apt/apt.conf.d/20auto-upgrades

You should see:

APT::Periodic::Update-Package-Lists "1";
APT::Periodic::Unattended-Upgrade "1";

By default, only the security repository is enabled for automatic upgrades, which is exactly what we want on a server: security patches yes, surprise major version bumps no.

Final checklist

Before moving on, verify each item:

# 1. Root login refused
ssh root@YOUR_SERVER_IP
# Expected: Permission denied

# 2. Password auth refused (from a machine without your key)
ssh -o PubkeyAuthentication=no deploy@YOUR_SERVER_IP
# Expected: Permission denied (publickey)

# 3. Firewall active
sudo ufw status | head -1
# Expected: Status: active

# 4. Fail2ban running
sudo systemctl is-active fail2ban
# Expected: active

# 5. Auto-updates configured
sudo unattended-upgrade --dry-run --debug 2>&1 | tail -5

If all five checks pass, congratulations: your VPS just went from "free real estate for botnets" to a solid foundation.

What's next

In Part 2, we install the actual platform: Docker, K3s (a lightweight Kubernetes distribution that fits comfortably in 8 GB of RAM), Traefik v3 as reverse proxy, and cert-manager for automatic Let's Encrypt certificates. By the end of it, any app we deploy will get HTTPS with zero manual certificate handling.

DEV Community: adeutou

nx-safe-suite: A Deep Dive Into Five Production-Grade Next.js Packages

@nx-safe-suite/env: Validation That Stops the Process

The problem

The solution

The design decision worth noting

@nx-safe-suite/api-response: A Contract Your Frontend Can Rely On

The problem

The solution

@nx-safe-suite/route-guard: Authentication Without the Boilerplate

The problem

The solution

@nx-safe-suite/server-cache: Multi-Tier Caching That Composes

The problem

The solution

@nx-safe-suite/audit-log: Logging That Survives Compliance

The problem

The solution

The Numbers

A Note on What This Demonstrates

Links

I Built Five npm Packages to Solve the Five Problems Every Next.js Backend Ignores

The Problem With "Just Use process.env"

What nx-safe-suite Is

The Architecture Decision: Why Not a Framework?

The Monorepo Structure

The Dependency Philosophy

Quality Signals

The Library Mindset

Where to Find It

Electricity Planning Engine, part 2: A Reader Comment Found a Real Gap in My Test Suite (and How I Fixed It)

The part that stung a little

The fix

Proving the test actually tests something

Thanks, Alex

Electricity Planning Engine: An Hourly Arbitrage API for Batteries and Solar, Plus the Timezone Bug That Almost Broke It

Why hourly prices are not a gimmick

Building it: the domain first

Contracts are strategies, not prices

A battery that refuses to lie about its own limits

Two engines, one lesson in greed

The bug that lied to me for a day

Try it yourself

The pipeline behind it

Why this matters beyond the demo

Self-Hosting Like a Pro, Part 4: Monitoring with Prometheus, Grafana and Loki, plus a CI/CD Pipeline That Actually Works

The monitoring stack and its budget

Three installation traps on K3s

Exposing Grafana safely

The CI/CD pipeline

Five pipeline failures and their fixes

The bonus bug: a page frozen in time

Where we stand

Self-Hosting Like a Pro, Part 2: Docker, K3s and Traefik v3 with Automatic HTTPS

Why Kubernetes on a single VPS?

What you need

Step 1: Install Docker

Step 2: Install K3s

Step 3: Install Helm

Step 4: Install Traefik v3

Step 5: Install cert-manager

Step 6: Deploy a test app with automatic HTTPS

Final checklist

What's next

Self-Hosting Like a Pro, Part 1: Hardening a Fresh Ubuntu VPS

Why bother with hardening?

What you need

Step 1: First login and system update

Step 2: Create a non-root user

Step 3: SSH key authentication

Step 4: Harden the SSH daemon

Step 5: Firewall with UFW

Step 6: Fail2ban

Step 7: Automatic security updates

Final checklist

What's next