If you skipped the prereq article, here’s the ten-second version: n8n is a self-hosted, visual workflow automation tool. Drag nodes onto a canvas, wire them together, hit save. Each node does one thing — HTTP request, database query, transform a payload, send an email. The workflow runs on a schedule, on a webhook, or on demand.

Think of it as Zapier you can host yourself. Or, if you’re a sysadmin, think of it as a graph editor on top of cron, curl, jq, psql, and an SMTP client. That’s roughly what’s happening under the hood. The visual editor saves you from writing the bash glue yourself, and from writing the YAML to describe the bash glue, and from writing the playbook to deploy the YAML.

I picked n8n for the homelab for a few specific reasons:

• Self-hosted. It runs in a Docker container on my own hardware. No data leaves the building unless I explicitly send it somewhere.
• Community edition is free. Not a trial. Not a freemium upsell. Free with sensible limits.
• MCP server exists. I can manage workflows from Claude Code without clicking through the UI. That alone saves me hours per month.
• It has the right primitives. HTTP, SQL, schedule, webhook, code, and a respectable library of pre-built integrations. That covers ~90% of what a homelab needs.

What it isn’t: a programming environment. The Code nodes are real JavaScript, but you don’t get a debugger, you don’t get version history (in community edition), you don’t get linting. If your workflow grows past 25 nodes you’re going to feel it. The visual editor goes from “elegant” to “spaghetti” somewhere around node 30, and you start wishing you’d just written the whole thing in Python.

The pinball pipeline lives well below that complexity ceiling. The Stern workflow has 14 nodes. The IScored workflow has 8. Both are easy to read at a glance. That’s the right size for n8n.

If you’re new to it: install via Docker, build something tiny, then back up your work religiously. I wrote a whole article on the backup workflow — read that next, before you build anything you’d be sad to lose.

The Stern Insider leaderboard API is a single GET endpoint:

https://api.prd.sternpinball.io/api/v1/portal/leaderboards/?event_code=<code>&event_state=current&format=json

Pass an event code, get the current standings. No auth required for read access (the leaderboards are public-facing). The response looks like this — I’ve trimmed it for brevity, but the shape is real:

{
  "leaderboard": {
    "code": "xKJL-RGnLk-Eudye",
    "name": "MAW APR LEADERBOARD",
    "start_date": "2026-04-01T00:00:00Z",
    "stop_date": "2026-04-30T23:59:59Z",
    "titles": [
      { "title_name": "Iron Maiden", "title_code": "MDN" },
      { "title_name": "Foo Fighters", "title_code": "FOO" }
    ],
    "scores": [
      {
        "username": "PinballTina",
        "title_name": "Iron Maiden",
        "score": 4234567890,
        "initials": "PTN",
        "avatar_path": "https://...",
        "background_color_hex": "#bd93f9",
        "is_all_accesss": false
      }
    ]
  }
}

A few things to notice.

titles is a separate array from scores. The titles array maps machine names (“Iron Maiden”) to internal Stern codes (“MDN”). The scores array references machines by title_name — the human-readable name, not the code. So before I can insert anything into my database, I have to build a lookup map from titles, then join each score against it. That’s the first Code node in the pipeline.

username is the Stern Insider login, not the player’s display name or initials. It’s stable across tournaments. That’s why the Stern player matching problem is not a problem — the username is a real identity. I use it directly as my player_id.

is_all_accesss is misspelled. Three S’s, not two. That’s not my typo — that’s how Stern’s API spells it. My Code node carefully matches the misspelling because if Stern ever fixes it, my code breaks silently and starts returning undefined. I’ll fix it the day they do.

The mapping into my schema:

Plus a snapshot of the entire raw response into api_snapshots, so if I ever change the schema and need to re-derive something, the source-of-truth payload is still there.

The whole IScored matching system rests on one PostgreSQL function:

CREATE OR REPLACE FUNCTION normalize_player_name(name TEXT)
RETURNS TEXT AS $$
BEGIN
    RETURN LOWER(REGEXP_REPLACE(name, '[^a-zA-Z0-9]', '', 'g'));
END;
$$ LANGUAGE plpgsql IMMUTABLE;

Three operations: lowercase, strip everything that isn’t a letter or digit, return. Marked IMMUTABLE so PostgreSQL can use it in expression indexes. That’s important — without IMMUTABLE, the planner refuses to index on normalize_player_name(display_name) and every match query becomes a sequential scan of 330 rows. That’s not slow at this scale, but it would be eventually.

What it does to real names:

The LvlUpMidwest → lvlupmidwest collapse is the whole point. Stern lets you pick a username with arbitrary capitalization. IScored lets the bartender type whatever they want with arbitrary spacing. After normalization, both forms collide on the same key.

The match query is small:

SELECT player_id
FROM players
WHERE normalize_player_name(display_name) = normalize_player_name($1)
LIMIT 1;

If that returns a row, the IScored name has a Stern twin. The mapping gets written with match_status = 'auto_matched'. If it returns nothing, the mapping gets written with match_status = 'pending' and a synthetic player_id of the form iscored_<normalized_name>.

The mapping is keyed on the original IScored name, not the normalized one. That matters: if the same human types “PINBALL TINA” today and “pinball tina” tomorrow, they both normalize to pinballtina, but they show up as two distinct mapping rows. The matching query handles them both correctly because it normalizes on the fly. The mapping table is essentially a cache of “we’ve seen this exact spelling before; here’s what we decided.”

Once a mapping exists, it sticks. A future ingestion run that sees the same IScored name doesn’t re-evaluate — it just uses the cached player_id. That’s how Dennis’s manual decisions persist. He clicks “link this to player X” once, the row is updated to manual_matched, and every future score under that exact spelling lands under the right player without further intervention.

The 35% auto-match rate is what it is. The remaining 46 pending mappings are mostly people who play at the bar regularly but have never created a Stern Insider account — they’re not on Stern at all. There’s nothing to match against, so they sit pending until Dennis confirms them as new IScored-only players. That’s not a failure mode; that’s the system working correctly.

Dennis has an admin page behind Cloudflare Access. From the outside, it’s a single HTML page served by the Flask app, no JS frameworks, no SPA, nothing fancy. Three sections stacked vertically:

1. Stats cards at the top. How many auto-matched, how many manual-matched, how many pending. Big numbers, plain font, instant glance.
2. Pending review table. One row per pending IScored name, with the normalized form and creation timestamp. Three buttons per row: Link to existing player, Confirm as IScored-only, Ignore (rare; for clearly-bad data like test names).
3. All mappings view. A read-only audit log. Every IScored name ever seen, what it’s currently mapped to, and what status it’s in. Useful when Dennis wants to undo a previous decision.

The link flow is the part that does the actual work. He picks a pending row. Clicks Link. A modal opens with a search box pre-populated with the normalized name. He types or scrolls until he finds the right Stern player. Confirms. The backend hits this update:

UPDATE iscored_player_mapping
SET player_id = $stern_player_id,
    match_status = 'manual_matched'
WHERE iscored_name = $original_name;

That’s the entire link operation. One update statement. The next ingestion run (within 10 minutes) re-attributes any new scores under that name to the correct player. Old scores are also retroactively correct because the leaderboard cache recomputes from high_scores_archive, which already has the new player_id foreign-keyed in.

The Confirm as IScored-only flow is even simpler. The mapping flips from pending to new_player, and the synthetic iscored_<name> player_id stays in place. Their scores show up on the leaderboard under that name from then on. If they later create a Stern account and Dennis wants to merge them, that’s a follow-up manual link.

There is no automation in the admin UI. There are no “smart suggestions” or LLM-powered match recommendations. There’s a search box, a list of player IDs, and Dennis’s brain. That brain knows which regulars play under which name. Software does not. So the software gets out of the way and lets the brain do its thing.

Dennis touches this UI maybe once a tournament. He doesn’t get an alert when there are pending mappings — he just remembers to check it after a busy weekend. The pending count is bounded (at most a few new players per month), the work per row is seconds, and there’s no ambiguity in the workflow. That’s the whole design goal: keep the human’s job small enough that it doesn’t feel like a job.

If I polled the Stern API every minute, all day, all night, I’d make 1,440 API calls per day per workflow. With the IScored workflow doing the same, that’s 2,880 calls/day for two leaderboards that update at the speed of human pinball. That’s stupid. Let’s do better.

The Stern workflow has two schedule triggers:

Both fire independently. Both call the same fetch node downstream. n8n doesn’t dedupe — if both trigger at exactly 10:00:00 AM, the workflow runs twice. In practice, they don’t collide because the 10-minute cron fires at minute 0, 10, 20, 30, 40, 50, and the hourly fires at minute 0. So they overlap once per hour during peak hours.

The math, generously rounded:

Off-peak window: 10 hours (midnight -> 10am)
  - Hourly cron only -> 10 runs

Peak window: 14 hours (10am -> midnight)
  - Hourly cron: ~14 runs
  - 10-min cron: 6/hr x 14h = 84 runs
  - But: ~14 collisions/hour where both crons fire at the same minute
  - Effective: ~84 runs (the hourly is dominated by the 10-min during peak)

Total: ~94 calls/day

That’s what the workflow’s own sticky note claims, and it’s close enough to true that I haven’t bothered to argue. Even at the upper bound (~108 if you count every overlap as a separate run), it’s an order of magnitude better than 1,440.

Why this shape and not something else?

Hourly baseline because new scores can land at any hour. Bartenders close out at 1 AM, but I’ve seen scores get processed by Stern’s backend at 3 AM as the system catches up on whatever’s queued. A 60-minute baseline means the worst case for a stale score is 60 minutes — that’s fine for a leaderboard nobody is staring at when the bar is closed.

10-minute peak because that’s the sweet spot between “keeps the kiosk feeling live” and “doesn’t hammer Stern.” A score change shows up in 5 minutes on average, 10 minutes worst case. Fast enough that customers checking the kiosk see their score reflected quickly. Slow enough that Stern’s API doesn’t notice me.

Cron, not state machines. I covered this in the main article. The temptation to build something feedback-driven was real. The reasons not to are stronger. Two crons. Same pipe. Done.

IScored at fixed 10-minute because I haven’t bothered to give it the dual-trigger treatment yet. It’s a single Schedule Every 10 Min trigger, 144 calls/day, every day. That’s on the backlog. The pattern is right there waiting whenever I get tired of the 50 extra daily calls.

If I needed to widen the peak window or speed up the cadence, it’s a single cron expression to edit. */10 9-23 for 9am-11pm. */5 10-23 to drop to 5-minute peak. No state, no migration, no thinking. That’s the entire reason to build it this way.

The pinball database has six tables that matter, plus a couple of auxiliary ones for snapshots and history. Here are the key ones, columns trimmed to the essentials:

-- Players: every human who has ever scored, Stern or IScored
CREATE TABLE players (
    player_id          VARCHAR(100) PRIMARY KEY,
    display_name       VARCHAR(100),
    normalized_name    VARCHAR(100),  -- materialized for fast match lookups
    avatar_url         TEXT,
    background_color_hex VARCHAR(7),
    is_all_access      BOOLEAN DEFAULT FALSE,
    last_seen          TIMESTAMP WITH TIME ZONE
);
CREATE INDEX idx_players_normalized ON players(normalized_name);

-- Machines: every active and historical pinball cabinet
CREATE TABLE machines (
    machine_id    VARCHAR(50) PRIMARY KEY,   -- short code: AFM, MDN, FOO, etc.
    machine_name  VARCHAR(100),              -- "Iron Maiden", "Attack from Mars"
    is_active     BOOLEAN DEFAULT TRUE
);

-- Events: monthly tournaments
CREATE TABLE events (
    event_code   VARCHAR(100) PRIMARY KEY,
    event_name   VARCHAR(200),
    start_date   TIMESTAMP WITH TIME ZONE,
    stop_date    TIMESTAMP WITH TIME ZONE,
    location_id  VARCHAR(20),
    event_type   VARCHAR(50),                -- 'STERN_LEAGUE', etc.
    is_active    BOOLEAN DEFAULT FALSE       -- exactly one row should be true
);

-- High_Scores_Archive: every score, ever, append-only
CREATE TABLE high_scores_archive (
    score_id      BIGSERIAL PRIMARY KEY,
    player_id     VARCHAR(100) REFERENCES players(player_id),
    machine_id    VARCHAR(50)  REFERENCES machines(machine_id),
    high_score    BIGINT NOT NULL,
    date_set      TIMESTAMP WITH TIME ZONE,
    event_code    VARCHAR(100) REFERENCES events(event_code),
    score_source  VARCHAR(20),                -- 'API' (Stern) or 'ISCORED'
    is_approved   BOOLEAN DEFAULT TRUE,
    CONSTRAINT unique_score_per_event
        UNIQUE (player_id, machine_id, high_score, event_code)
);
CREATE INDEX idx_hsa_event_player ON high_scores_archive(event_code, player_id);
CREATE INDEX idx_hsa_event_machine ON high_scores_archive(event_code, machine_id);

-- IScored mapping tables
CREATE TABLE iscored_machine_mapping (
    iscored_game_id VARCHAR(20) PRIMARY KEY,
    machine_id      VARCHAR(50) REFERENCES machines(machine_id),
    last_synced     TIMESTAMP WITH TIME ZONE
);

CREATE TABLE iscored_player_mapping (
    iscored_name    VARCHAR(100) PRIMARY KEY,
    normalized_name VARCHAR(100),
    player_id       VARCHAR(100) REFERENCES players(player_id),
    match_status    VARCHAR(20) DEFAULT 'pending',
    created_at      TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
CREATE INDEX idx_iscored_normalized ON iscored_player_mapping(normalized_name);

The interesting constraint is unique_score_per_event on high_scores_archive. It includes the score value, which is unusual — most “score table” designs would use (player_id, machine_id, event_code) and update the high score on conflict. I deliberately don’t. Including the score value means a player improving their own score creates a new row, not an update. The model is “append every distinct score” rather than “keep only the best.”

That gives me three things:

1. Idempotent ingestion. Re-running yesterday’s pull is a no-op. Same player, same machine, same score, same tournament → blocked by the unique constraint, no action taken.
2. Score progression history. I can answer “show me how this player improved on Iron Maiden over the month” because every score they posted is in the table.
3. Cheap deduplication. No need for application logic. PostgreSQL refuses the duplicate at the constraint level. ON CONFLICT ON CONSTRAINT unique_score_per_event DO NOTHING and move on.

There’s also a leaderboard_cache table I didn’t list — it’s the precomputed standings for the active tournament, recalculated by a stored procedure (update_combined_leaderboard) at the end of every ingestion run. The Flask app reads from it directly. Recomputing it takes well under a second on a database this small, so I don’t bother with incremental updates. Full rebuild every 10 minutes is plenty cheap.

Pre-deployment review is the entire reason I work in InfoSec, so let me show what one looks like in practice.

While building the admin endpoints for the IScored UI, I sketched out a small POST endpoint that the n8n workflow could use to push article-style content into the database. Internal-only, of course. n8n is on the same Docker network, so it could just POST directly. Easy.

I named the route /api/save-article, wrote the handler, ran a manual curl against it from my laptop, and watched it accept anonymous unauthenticated input from outside the firewall.

That’s the moment to stop. Not the moment to ship.

The route as I’d written it had three problems, and I want to be precise about them because they’re common mistakes in homelab Flask apps:

1. No authentication boundary. Cloudflare Access protects most of the site, but this specific path was sitting under /api/* which was being routed publicly. The internal/external distinction wasn’t being enforced — it was being assumed.
2. No size limit. The handler was happy to accept a multi-megabyte body and try to write it. That’s a denial-of-service vector by accident.
3. No input validation on identifiers. The article_id field was a free-text string going straight into a SQL query (parameterized, thankfully) and a filesystem path (not parameterized).

The fix wasn’t a single change. It was four:

1. Move the route under /api/admin/. That namespace is covered by an existing Cloudflare Access policy. External requests get bounced at the edge before they ever reach Flask.
2. n8n bypasses Cloudflare via internal IP. The workflow hits the Flask container directly on the Docker network. It doesn’t go through the public hostname, so the Cloudflare Access policy doesn’t care about it. That preserves the “internal automation can do its job” use case without re-introducing the public hole.
3. Add a 1 MB size cap on the request body via Flask’s MAX_CONTENT_LENGTH. Anything bigger gets a 413 before the handler runs.
4. Validate the identifier. The article_id parameter is now restricted to [a-zA-Z0-9_-]+ via a regex check at the top of the handler. Anything else gets a 400.

None of this is novel. Every one of these is in the OWASP top ten in some form. The point of the story isn’t “I invented secure coding.” The point is: this got caught before it shipped because I tested it. A curl from my laptop is not a fancy test rig. It’s two minutes of effort. The cost of finding this bug before deployment was negligible. The cost of finding it after deployment, when something on Reddit linked to my homelab and a bored teenager started posting test data, would have been… a lot more.

If you’re building HTTP endpoints in a homelab project, take this lesson seriously: do not trust your own assumptions about what’s reachable from the public internet. Test with curl from outside your network. Read the route handler with adversarial eyes. The bug you find in five minutes today is the incident you don’t have to write up next year.

Six things that actually save time when something in n8n breaks. Earned the hard way.

1. Test one node at a time. The big green Execute Workflow button at the bottom is for production runs. While you’re debugging, click the play icon on the individual node that’s misbehaving. n8n will run just that node using whatever data is sitting in the previous node’s output. You don’t burn API calls, you don’t spam your database, you just see what this node does to that input.

2. Pin test data on the trigger node. When you’re iterating on a workflow that fires off an HTTP API call, every test run hits the API. Eventually you’ll get rate-limited, or the data will change, or the API will go down at the worst possible time. Right-click the trigger node, choose “Pin data,” and feed it a known-good payload from a previous successful run. Now your tests are deterministic and the API stops getting harassed.

3. Read the actual node output, not what you assumed it produced. This is the single most common mistake. You wired up an HTTP request, you “know” it returns a list of objects, you wired the next node to map over that list — but the API actually returned an object with a data property containing the list, and now your map gets one item with weird keys. Click the previous node, look at the Output tab, see what’s actually there. Believe your eyes, not your model of the API.

4. Use the execution log when things “work but don’t.” Sometimes a workflow runs to completion but produces no observable effect. Maybe the database insert silently no-op’d. Maybe the email node thinks it sent something but the SMTP server quietly dropped it. The Executions tab on the left shows every run with its full per-node input/output. You can replay history at the node level. Use it.

5. Watch out for the credential-change bug. Changing the credential on a node sometimes blanks the rest of the node’s parameters. (I’m not making this up; I’ve seen it on the Postgres node specifically.) Always save and reopen the node after a credential change to verify the SQL or HTTP body is still intact. If it’s blank, undo and retype.

6. Webhook 404s after creating via MCP. If you create a webhook node via the MCP API and the webhook returns 404 even though the workflow is active, it’s almost certainly missing the auto-generated webhookId field. Toggle the workflow off and back on to re-register it. That has fixed it for me every single time.

There’s one thing I would add that isn’t really a tip: Claude is good at this, but you have to feed it the right context. Show it the exact node configuration. Show it the actual error message. Show it the input the node received. Don’t ask “why is my workflow broken” — ask “given this input and this node config, why is this output not what I expected.” The more specific the question, the better the answer. AI is a force multiplier, not a force creator.