DEV Community: Cyrille Sepele

Build a POS receipt printer in Node.js

Cyrille Sepele — Sun, 16 Aug 2026 12:27:34 +0000

Disclosure: I build Receiptful, the printing API used in this tutorial. The Node and Express parts apply whatever you print with.

You have orders coming into your point of sale, and you want each one to print on the thermal printer at the counter. This is a complete walkthrough of a small Node service that does exactly that. By the end you will have an endpoint you can POST an order to and watch paper come out.

There is nothing to install next to the printer for this tutorial to work, and no ESC/POS to write by hand. You send HTML, Receiptful prints it.

Before you start

You need two things from the console:

A paired printer, which gives you a printer ID. If you have not done this yet, the getting started guide walks through it in a couple of minutes.
An API key (the rf_live_… value), created under API keys and shown only once.

On the code side you need Node 18 or newer, so that fetch is available globally with no extra dependency. We will use TypeScript, but the same code works in plain JavaScript if you drop the types.

Put your credentials in the environment rather than in the source:

export RECEIPTFUL_API_KEY="rf_live_3f9c…"
export RECEIPTFUL_PRINTER_ID="42"

Step 1: model the order

Start with the shape of an order. Yours will have more fields, but this is enough to print a useful receipt:

interface LineItem {
  name: string;
  quantity: number;
  unitPrice: number; // in cents, to avoid float rounding
}

interface Order {
  id: number;
  items: LineItem[];
  placedAt: Date;
}

Keeping money in cents and formatting only at the edges saves you from the classic floating point rounding bugs that show up as a receipt total that is one cent off.

Step 2: render the order as HTML

This is the part that decides how the receipt looks. Receiptful converts the HTML you send into ESC/POS for your specific printer, so you get to lay a receipt out with tags you already know instead of byte codes.

function money(cents: number): string {
  return "$" + (cents / 100).toFixed(2);
}

function renderReceipt(order: Order): string {
  const lines = order.items
    .map((item) => {
      const total = money(item.unitPrice * item.quantity);
      return `<tr><td>${item.quantity}x ${item.name}</td><td align="right">${total}</td></tr>`;
    })
    .join("");

  const grandTotal = money(
    order.items.reduce((sum, i) => sum + i.unitPrice * i.quantity, 0),
  );

  return `
    <h1 style="text-align:center">CAFE MILA</h1>
    <p style="text-align:center">Order #${order.id}</p>
    <hr>
    <table width="100%">${lines}</table>
    <hr>
    <table width="100%">
      <tr><td><b>TOTAL</b></td><td align="right"><b>${grandTotal}</b></td></tr>
    </table>
    <p style="text-align:center">Thank you</p>
  `;
}

Receipt paper is narrow, so keep the layout to a single column and let text wrap. There is more to say about designing for a 58mm roll, but this is enough to print something clean.

Step 3: send it to the printer

Now POST the HTML to the printer's job endpoint. One authenticated request creates the job:

const API = "https://api.receiptful.io/v1";
const KEY = process.env.RECEIPTFUL_API_KEY!;
const PRINTER = process.env.RECEIPTFUL_PRINTER_ID!;

async function printReceipt(order: Order): Promise<number> {
  const res = await fetch(`${API}/printers/${PRINTER}/jobs`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${KEY}`,
      "Content-Type": "text/html",
    },
    body: renderReceipt(order),
  });

  if (!res.ok) {
    const detail = await res.text();
    throw new Error(`Print request failed (${res.status}): ${detail}`);
  }

  const job = await res.json();
  return job.id as number;
}

The response is the job that was created, and a second or so later the receipt prints:

{
  "id": 9281,
  "printer_id": 42,
  "status": "created",
  "lifetime_seconds": 600,
  "created_at": "2026-07-16T10:24:01Z",
  "expires_at": "2026-07-16T10:34:01Z",
  "status_updated_at": "2026-07-16T10:24:01Z"
}

Step 4: wrap it in an endpoint

Put that behind a route so your checkout can call it. Here it is with Express:

import express from "express";

const app = express();
app.use(express.json());

app.post("/orders/:id/print", async (req, res) => {
  try {
    const order: Order = req.body;
    const jobId = await printReceipt(order);
    res.status(202).json({ jobId });
  } catch (err) {
    console.error(err);
    res.status(502).json({ error: "Could not queue receipt" });
  }
});

app.listen(3000);

Returning 202 Accepted is deliberate. The job is queued, not yet confirmed printed, and that distinction matters at a busy counter. The next step is how you close that gap.

Step 5: confirm it actually printed

A receipt endpoint that returns success the moment the request is accepted will happily report a print that never reached paper, because the printer was off or out of range. If it matters that the receipt printed, poll the job until it reaches a final state:

async function waitForPrint(jobId: number, timeoutMs = 15000): Promise<string> {
  const deadline = Date.now() + timeoutMs;

  while (Date.now() < deadline) {
    const res = await fetch(`${API}/printers/${PRINTER}/jobs/${jobId}`, {
      headers: { Authorization: `Bearer ${KEY}` },
    });
    const job = await res.json();

    if (["completed", "failed", "expired"].includes(job.status)) {
      return job.status;
    }
    await new Promise((r) => setTimeout(r, 1000));
  }
  return "timeout";
}

A job moves through created, notification_sent, notification_received, printing, and then completed. If the printer never answers, the job expired instead of printing a stale order, which is exactly what you want at closing time. How you react to failed or expired, whether that means a retry, an on-screen alert, or a reprint button for staff, depends on your counter, so it is worth deciding on purpose rather than by default.

That is the whole thing

Roughly sixty lines and you have order to paper, with a real status check rather than a hopeful fire and forget. No print server, no drivers, no ESC/POS.

The first 20 receipts each month are free, no card required, so you can build this against a real printer today.

Open the console to grab a printer ID and key, or read the API docs for every field.

GitLab CE Comes Without a Runner: Why Nothing Executes Your Pipelines

Cyrille Sepele — Wed, 12 Aug 2026 21:31:26 +0000

You installed GitLab Community Edition, pushed a .gitlab-ci.yml, and watched
the pipeline sit at pending until it went grey. No error, no failed job,
nothing in the logs worth reading.

Nothing is broken. Your instance has no runners, and it never had any.

Why a fresh instance has none

GitLab is two things that people assume are one thing. There is the application:
repositories, issues, merge requests, the CI/CD system that reads your
.gitlab-ci.yml and builds a pipeline out of it. And there is GitLab Runner: a
separate program, on a separate machine, that actually executes jobs.

The Omnibus package installs the first. It does not install the second, and it
does not come with any machines to run it on.

The confusion comes from GitLab.com, where shared runners are switched on by
default and most people's first experience of CI is that it simply works. That
shared fleet is hardware GitLab owns and operates as part of their hosted
service. It is not part of the software you downloaded, so it does not come
across when you run your own instance.

So on a self-managed install, GitLab will happily accept your pipeline
definition, parse it, create the jobs, and queue them. Then it waits for a
runner to ask for work. If no runner ever asks, the jobs wait indefinitely.

Confirming it in thirty seconds

Go to Admin Area → CI/CD → Runners on your instance. If the list is empty,
that is your answer.

For a single project, Settings → CI/CD → Runners shows the same thing scoped
narrower. A fresh instance shows nothing in either place.

From the command line on the GitLab server:

sudo gitlab-rails runner "puts Ci::Runner.count"

If that prints 0, no runner has ever been registered against this instance.

One thing worth ruling out at the same time: a job can also sit pending when
runners do exist but none of them match the job's tags. If your runner list is
not empty, check whether your jobs specify tags: that no runner carries. That
is a different problem with a different fix, and it is the second most common
cause after this one.

Your three ways out

Install a runner yourself

The traditional answer. Take a machine, install the gitlab-runner package,
register it against your instance with a token from the runners page, and pick
an executor. The Docker executor is the usual choice because it gives each job a
clean container.

This is genuinely the cheapest option on day one, and if you have a spare server
and one project that never changes, it may stay that way. Budget an afternoon
for the first one, less if you have done it before.

The cost arrives later, and it arrives quietly. Runner versions drift out of
support. Disks fill with old build caches until a job fails for reasons that
look nothing like a disk problem. The machine accumulates undocumented local
changes, and eventually nobody is quite sure how to rebuild it. None of this is
hard, exactly. It is just permanent.

Build a runner fleet

At real scale you stop managing machines individually and start managing a
system: the Kubernetes executor, or Docker Machine autoscaling, defined in
Terraform, with runners created and destroyed on demand.

If you already run Kubernetes, this is probably the right answer and you should
skip the rest of this post. It is worth being clear-eyed that it is a platform
project rather than a task, with a platform project's ongoing maintenance. Teams
regularly underestimate this by a factor of several because the first working
version comes together quickly.

Rent a dedicated runner

Someone else provisions the machine, installs the runner, registers it against
your instance, and keeps it patched. You get a single-tenant VM that behaves
like any other runner on your runners page.

The trade you are making: you stop owning the machine's lifecycle, and you
accept that build compute runs outside your network. Which brings us to the part
that matters most.

The requirement nobody mentions upfront

If you rent runners, your GitLab instance has to be reachable from that runner
over the public internet, on https, with a valid certificate.

That is not a vendor preference, it is how the protocol works. The runner polls
your instance for jobs, and registration calls your instance's API. Both need a
public hostname that resolves to a public address.

That covers most self-managed instances at companies and agencies, which sit on
a real domain behind a real certificate. It does not cover an air-gapped
instance, a VPN-only instance, or one bound to a private network. If that is
you, the answer is a runner inside your perimeter, and no hosted service can
change that.

Better to know in paragraph twenty than after signing up.

Being straight about what a runner sees

A runner clones your source in order to build it. That is true of every runner
ever created, including one you install yourself on your own hardware. Anyone
implying otherwise is selling something.

So the useful question is not whether build compute touches your code. It is
what kind of machine touches it, and who else is on that machine.

A shared runner is multi-tenant. You did not choose the hardware, you cannot see
what ran on it before your job, and you cannot point at it in an audit. A
dedicated VM is yours alone, in a region you picked, destroyed when you delete
it. That is a posture you can describe to a client security review, which a
shared runner never was.

Which one is actually right for you

If you self-host GitLab because a policy requires source to stay inside your
network, and that policy extends to build compute, install your own runners.
That is the whole answer and the rest is noise.

If you self-host for the more common reasons, keeping control of your data,
avoiding SaaS lock-in, satisfying a client contract about where the repository
lives, then the repository decision and the build compute decision are separate,
and most teams only ever made the first one deliberately.

Agencies feel this hardest, because the problem repeats per client. Eight
clients on their own instances means eight runner setups, eight sets of
credentials, eight machines to patch, and an awkward question at the end of
every engagement about what is still sitting on that box.

The short version

Your pipelines are pending because a self-managed GitLab ships with no runners,
by design. Install one, build a fleet, or rent one, and pick based on how much
of your attention you want the choice to keep asking for after the first green
pipeline.

If renting sounds right, runners for self-hosted GitLab explains
how connecting your own instance works, including what stays on your side.

We Cut Our GitLab Build Time by 59% With One Change

Cyrille Sepele — Sat, 16 May 2026 20:58:07 +0000

You know the feeling. You push a one-line fix, open the pipeline, and watch your runner spend two minutes downloading node_modules. Again. The same node_modules it downloaded ten minutes ago. On the last push. That was also a one-line fix.

Shared runners have the memory of a goldfish. And you're paying for it in build minutes.

The problem: shared runners forget everything

GitLab's shared runners are ephemeral by design. Each job gets a clean machine. Great for isolation. Terrible for your afternoon.

Every single job:

Docker pulls your base images from scratch
npm install / pip install / bundle install downloads every dependency again
Docker-in-Docker builds re-download every layer, every time
Your test suite can't reuse compilation artifacts from the previous run

"But there's the cache: keyword!" Sure. It uploads a tarball to object storage and downloads it on the next run. In practice:

Uploading and downloading a 500MB archive takes its own sweet time
Cache misses are silent and frequent (good luck debugging that)
Docker image layers? The cache: keyword can't help you there. You end up in a rabbit hole of registry-based workarounds and BuildKit inline caching

For small projects, whatever. For anything with real dependencies or Docker builds, you feel it on every push.

What happens when the cache actually sticks around

When your runner lives on a dedicated machine that doesn't self-destruct after each job, things get better fast:

Docker layer cache just works. Your FROM node:20 isn't pulled every run. Your RUN apt-get install layer is already built. Docker's native caching does what it was designed to do. No config, no tricks.

The /cache volume persists between jobs. GitLab runners support a local cache directory mounted as a Docker volume. On a shared runner, that volume dies with the VM. On a dedicated machine, it stays. Your cache: directive in .gitlab-ci.yml writes to local disk instead of round-tripping through S3.

Docker-in-Docker benefits the most. If you're building container images in CI, a persistent Docker daemon means every subsequent build reuses layers from previous builds. No registry hacks. No BuildKit configuration. Just Docker doing its thing.

None of this is magic. It's just what happens when your runner isn't destroyed after every job.

Proof: same job, same project, very different numbers

Here's our build app job:

Same job. Same codebase. 59% faster. And that's a warm cache. The first run is comparable to a shared runner. Every run after that benefits from Docker layers and dependencies already sitting on disk.

The queue time drop matters too. Shared runners serve everyone on GitLab.com, so your job waits in line behind strangers. A dedicated runner picks up your job immediately because it has nothing better to do.

Now multiply that by 50 pipeline runs a day.

"I'll just self-host a runner."

You can. And if you have a dedicated ops person, or you genuinely enjoy debugging Docker daemon crashes on a Saturday morning, go for it.

For everyone else:

Provisioning the server and keeping it updated
Installing and configuring Docker + GitLab Runner
Monitoring disk space (those Docker layers add up quietly)
Rotating tokens, managing SSH keys
Getting paged at 2 am because the runner went offline

The cache benefits of a persistent runner are real. The Sunday afternoon you lose figuring out why /var/lib/docker filled up the disk is also real.

What we built instead

This is why RocketRunner exists.

You get a dedicated VM. Real hardware, not a shared slice. Docker and the GitLab runner are installed and registered with your project automatically. Because it's your machine running your Docker daemon, all caching works natively.

You don't configure any of this. It's a side effect of having a runner that doesn't get thrown away after every job.

What this looks like in your `.gitlab-ci.yml`

Typical Node.js setup:

build:
  stage: build
  image: node:20
  cache:
    key: ${CI_COMMIT_REF_SLUG}
    paths:
      - node_modules/
  script:
    - npm ci
    - npm run build

On a shared runner, npm ci downloads everything every time. The cache round-trip to S3 often takes longer than the install itself. Ironic.

On RocketRunner, that cache lives on a local volume. First run populates it. Second run reads from disk. Done.

For Docker builds, the gap gets embarrassing:

build-image:
  stage: build
  image: docker:24.0.5
  services:
    - docker:24.0.5-dind
  script:
    - docker build -t myapp:latest.

Shared runner: pulls docker:24.0.5, pulls every layer in your Dockerfile, every time. A 3-minute build that should take 20 seconds. You go make coffee. You come back. It's still pulling.

RocketRunner: Docker daemon is already running. Base images are cached. Unchanged layers are skipped. It finishes before you can alt-tab away.

When this matters (and when it doesn't)

Good fit:

Projects with Docker-in-Docker builds
Monorepos with large dependency trees
Teams running 20+ pipelines per day
Anything where npm install takes longer than your actual tests

Probably overkill:

Small projects with minimal dependencies
Pipelines that only run linters or simple scripts
Teams running fewer than a handful of pipelines per week

Try it

RocketRunner starts with a 48-hour free trial. Setup takes about 2 minutes. Connect your GitLab account, pick a server size, choose a region, and your runner is live.

Smallest plan runs at $0.018/hr with a $10.59/month cap. Most teams pay between $1-10/month.

If your pipelines spend more time downloading dependencies than running your actual code, a persistent cache might be all you need.

Cheap Dedicated CI/CD Runners for GitLab: Shared vs Self-Hosted vs Rented

Cyrille Sepele — Sat, 09 May 2026 21:01:17 +0000

If your GitLab pipelines are slow, flaky, or eating into your SaaS bill, you've probably looked at your runner setup. There are three ways to run GitLab CI jobs, and the cost difference between them is bigger than most people realise.

The shared runner problem

GitLab's shared runners are the path of least resistance. You don't set anything up, and they work. Until they don't.

The issues show up gradually:

Jobs queuing behind other users' workloads
Inconsistent build times
No control over the hardware
Shared filesystem state that causes flaky tests you can't reproduce locally
No pipeline caching — every job starts cold, every time
Limited CI minutes on the Free tier (400 min/month on GitLab.com)
Extra minutes cost $10 per 1,000 if you exceed your allowance

If you're running Docker-in-Docker or anything that needs real isolation, shared runners are a constant source of friction.

For a solo project or a weekend hack, shared runners are fine. For a team shipping to production, the unpredictability gets expensive fast.

Self-hosting: more control, more overhead

The obvious answer is to run your own runner on a VPS. Full control, no queuing, dedicated hardware. A Hetzner CX23 (4GB RAM) costs about €3.99/month on paper — hard to beat.

The catch is everything else:

Provision the server
Install Docker and the GitLab runner binary
Register it with your project or group (get the token, run the register command, handle the config)
Keep it updated
Monitor it
Remember to destroy it when you're done, or keep paying for it

The real cost of self-hosting isn't the €3.99/month server. It's the engineer who updates the runner binary when it falls behind, debugs the registration token when it expires, and gets paged when the disk fills up. If that's 30 minutes a month at a $50/hr developer rate, you've already spent more than the server costs.

For a team that already owns and operates infrastructure, this overhead is absorbed. For a solo developer, a startup, or anyone who just wants pipelines to work, it's babysitting you didn't sign up for.

Renting a dedicated runner by the hour

There's a third option that most people haven't considered: renting a dedicated runner, billed hourly, with zero setup.

The model works like this:

You sign in with GitLab
Pick a server size and region
The runner is provisioned and registered with your project automatically. No SSH, no config files
You pay only while the runner exists
Delete it, and billing stops immediately

RocketRunner does this. A Small runner (4GB RAM, 2 vCPUs) costs $0.018/hr, or about $10.59/month maximum if you run it 24/7. Most teams pay far less because they only run it when they need it.

The actual cost comparison

Option	Monthly cost	Setup time	Isolation
GitLab shared runners	Included (with limits)	0 min	None
Self-hosted on Hetzner CX23	~$4.71/month + engineering time	30–60 min	Full
Rented dedicated runner	$0.018/hr (~$1–10/month typical)	2 min	Full

The self-hosted option has the lowest server bill if you run jobs 24/7. But once you factor in the engineering time to set it up and keep it running, renting by the hour is cheaper for most teams.

When renting makes sense

You're a solo developer or small team that doesn't want to maintain infrastructure
You need full VM isolation (Docker-in-Docker, privileged containers, clean state per run)
Your pipeline load is unpredictable, and you don't want to pay for idle compute
You want runners in a specific region (EU or US) for compliance or latency reasons
You're prototyping and want something live in 2 minutes, not 45

The bottom line

Shared runners are free but unreliable. Self-hosting is cheap on paper but comes with hidden ops overhead. Renting a dedicated runner by the hour sits in between: full isolation, no setup, and a cost that scales with actual usage — no engineer babysitting required.

If you've been putting up with slow or flaky GitLab pipelines, it's worth trying a dedicated runner. With a 48-hour free trial and no contracts, the cost of finding out is zero.

Spin up a dedicated GitLab runner in 2 minutes

👉 Get started at rocketrunner.io — card required, no charge for 48 hours.