explainer-engine is an automated pipeline that turns one subject into a 40 to 60 second vertical explainer video. It picks a subject, pins a Wikipedia article, writes a script from it, fact-checks every sentence against the article, narrates with ElevenLabs, renders with Remotion, and uploads to YouTube.

The genre it runs now is true crime, and that raises the stakes. A made-up date in a science explainer is embarrassing. A made-up detail about a real person and a crime is an accusation. So most of the engineering isn’t the rendering at all. It’s the set of gates that decide what the language model is allowed to say, and the rule that the pipeline only covers cases a court has closed.

Like the other projects in this category, I built it by directing AI coding agents rather than writing the code myself. It has 35 commits over three days, and 33 carry a Co-Authored-By: Claude trailer. It’s about 34k lines of TypeScript, Python and Swift, with about 240 tests. My part was deciding the rules, and watching and listening to the output until it was good enough.

The pipeline 🏭

Most of the steps below are gates: points where the pipeline can say no. Select one to see what it checks and what happens when a subject or a draft fails, or press Play to walk a subject all the way to an upload.

Picking a subject 🔎

The autopilot crawls English Wikipedia crime categories two levels deep through the MediaWiki API (generator=categorymembers), with hard caps on how many listings and pages it reads. It drops articles under 40,000 bytes, because a thin article can’t back a script, and deduplicates subjects by their Wikidata ID.

Wikidata then narrows the list to a pool:

• A person must be a human (P31 = Q5) with P1399 “convicted of” set, who died at least two years ago.
• A case must have a date (P585) and a named perpetrator (P8032) who has P1399 on their own item.
• Some offence types are excluded outright: political violence, mass-casualty events, sexual crimes and crimes against children.

In the first measured build, 6,260 articles went in and 83 subjects came out.

The pool is only a convenience filter; it is not the safety guarantee. Wikidata can be wrong or out of date. The guarantee is the verdict gate, which reads the actual article.

Pinning the source 📌

source.ts fetches the article through the MediaWiki Action API with prop=extracts|info|pageprops|revisions and stores the revision id plus an oldid= permalink in source.json. Everything after this step works against that exact revision. If the article is edited tomorrow, you can still say exactly what the video was checked against.

Some other rules at this stage:

• Disambiguation pages and weak title matches are refused, not guessed at.
• Thin articles are refused: at least 700 words and 6 paragraphs.
• Block quotations are marked as unusable evidence. The pipeline reads the same revision’s wikitext to find them. A quote the article attributes to someone else isn’t the article saying it’s true.
• Paragraphs are numbered ([P1], [P2], and so on) so every later claim can point to where it came from.

Gate 1: the confirmed-conviction verdict ⚖️

Before a single word of script is written, verdict.ts reads the pinned article and decides whether the case is closed. It works in two layers and fails closed.

Layer one is plain code, with no model involved. Regex families look for:

• Conviction language, including older wordings like “was sent to jail”. The Mona Lisa thief’s article never actually uses the word “convicted”.
• Unresolved language: unsolved, cold case, awaiting trial, appeal pending.
• Contested language: overturned, pardoned, exonerated, acquitted, retrial, recanted.

No conviction phrase, or any unresolved phrase, is an instant refusal:

if (!check.conviction.length) {
  check.reasons.push('the article never states that anyone was convicted, pleaded guilty or was sentenced; ...');
  return check;
}
if (check.unresolved.length) {
  check.reasons.push(...check.unresolved.map((u) => `${u.token} ("${u.sentence}")`));
  return check;
}

Contested phrases become questions the model has to answer.

Layer two is one LLM call at temperature 0 with a strict JSON schema. The model returns the outcome, the defendants with verbatim evidence, whether the conviction still stands, and an answer to every flagged phrase. Then code audits the model:

• Every quote must be verbatim.
• It must be in the paragraph it cites.
• It must not come from a block quotation.
• The conviction quote must itself match the conviction patterns.

Any doubt the model reports is a refusal:

if (!['convicted', 'guilty plea'].includes(reading.outcome)) reasons.push(...);
if (!reading.convictionStands) reasons.push(...);
if (reading.appealPending) reasons.push(...);
if (reading.guiltDisputed) reasons.push(...);
if (reading.unsolved) reasons.push(...);

A refusal is permanent and is written to verdict.md with its reasons. Three real examples:

• Zodiac Killer: refused in layer one, with no model call.
• Lindbergh kidnapping: refused in layer two, because the guilt is disputed.
• 1911 theft of the Mona Lisa: confirmed, on the wording of one specific paragraph.

Gate 2: every sentence is checked against the article 🧾

The writer (Gemini by default, with schema-constrained JSON output) gets the numbered article and is told it is its only source. Along with the narration, it has to return a facts[] list. Each fact has a claim, the beat it belongs to, the paragraph id, and a verbatim quote as evidence.

A separate checker call then splits the narration into atomic claims. Every date, number, name, place, relationship and causal link is its own claim, and each gets supported, unsupported or contradicted, with a paragraph id and a quote.

Nobody trusts the checker either. Code checks the checker:

• Every quote must actually be in the article. The comparison ignores case, accents and dash variants, and quotes from block quotations don’t count.
• Every number in a sentence must appear in that sentence’s evidence.
• Qualifiers must survive: “more than 20,000” is not “about 20,000”.
• Hedges must survive: if the article says “believed to” or “often called”, so must the script.
• Every name must appear in the paragraph the claim cites.
• Every sentence must be covered by at least one claim.

Even before the model call, a cheap pass flags any number, capitalised name or quoted phrase in the narration that the article doesn’t literally contain.

When something fails, the findings go back to the writer, who rewrites. Sentences that already passed are “settled” and not re-checked. This runs for up to three rounds. A draft that still fails is rejected, and the whole audit is saved to factcheck.md. The accepted narration is audited one more time, and visual notes that name things the narration doesn’t are dropped, so the pictures can’t sneak in an unchecked claim either.

One near miss shows how small the gaps can be. The shot planner’s end card, which the narration checks never saw, said “The most famous painting in the world”. The article says “one of the best known”. End cards now go through their own hedge check (endCardHedges), and that wording fails.

Gate 3: the hook, on the page and in the ear 🎣

Short-form video lives or dies in the first two seconds, so the opening has its own gate, again in two parts.

Text rules, in code, before any voice credits are spent:

• No opening on a date or place phrase, a subordinate clause, or “It was…”.
• No questions, and no “Have you ever”, “Imagine” or “Did you know”.
• No stative verbs like “was born” or “became interested”.
• At most 22 words per sentence.
• At most 12 words of setup before the sentence that delivers the surprise.

An LLM judge compares the writer’s opening with 2 or 3 alternatives the writer also had to provide. A “strong” verdict is overridden in code unless the opening is concrete, has tension, is surprising and clear, and leaves the viewer with a question.

Timing rules, measured on the recorded narration:

export const HOOK_AUDIBLE_SECONDS = 1.0;  // first word heard by 1.0s
export const HOOK_POINT_SECONDS = 2.0;    // ...and 4 words said by 2.0s
export const HOOK_POINT_WORDS = 4;
export const HOOK_SETUP_WORDS = 12;
export const HOOK_TURN_SECONDS = 5.0;     // the twist lands by 5.0s

For a crime video, a failed timing check throws at compile time. It does not render with a warning.

How that gate got its timing rules

The first crime video opened: “A detective finished writing his report leaning on a table in Vincenzo Peruggia’s Paris apartment. The stolen Mona Lisa was hidden under that table.” It passed every text rule, and I still couldn’t follow it on listening. Measuring the take showed three separate problems:

1. The narration faded out on the twist. ElevenLabs ends a statement on a falling pitch. “Mona” came out at -14.0 dBFS and “table.” at -27.8 dBFS, 14 dB apart within one sentence.
2. The music was as loud as the reveal. The bed played at a fixed gain with no ducking. In the speech band, the reveal word ended 0.2 dB above the music.
3. The twist arrived at 5.88 s, behind fifteen words of setup and a name the aligner itself heard as “Peruzio’s”.

The fix went into the pipeline, not just that one script:

• Narration is levelled along its envelope, which brought the hook sentence’s spread from 14 dB down to 5.
• Every music bed is scaled from its own measured loudness and ducked under each spoken word.
• The setup and turn limits above were added, plus a rule that fails any capitalised name the aligner mishears.

The rewritten opening leads with the Mona Lisa, and its turn now lands at 3.93 s.

Voice and render 🎙️

• Narration: ElevenLabs eleven_v3_conversational, one take per scene, levelled to a fixed speech loudness. The standard v3 model was tried and rejected after listening. It reads at 0.48 to 0.50 s per word against 0.37 to 0.41, which broke every runtime and hook constant.
• Word timing: it doesn’t come from ElevenLabs. A local faster-whisper model is used as a forced aligner, and what it hears is matched back to the script with difflib. Words it can’t recover are recorded as misheard, and the hook gate uses that.
• Render: a video is a JSON VideoScript (scenes, then shots, one template per shot, from a library of 55) rendered by a single 1080x1920 Remotion composition. Timing is in word indices, not frames, so a re-voiced line re-times itself. The output is H.264 at CRF 20, loudness-normalised to -16 LUFS.
• Faces: Apple Vision face detection (a small Swift helper) checks every crop of a still image. The render refuses any crop that cuts off a head, after a painting in an early video showed a torso with no head. Checked against real face boxes, 11 of 14 portrait crops had failed.
• Publishing: a YouTube Data API resumable upload, then thumbnails/set. Afterwards it reads the privacy status back and fails on a mismatch. An unattended publish requires an accepted fact-check, ElevenLabs narration, a runtime of 40 to 60 s (±1 s) and a cover.

What broke on the way 🐛

• The gates contradicted each other. The first live autopilot subject used up the whole day’s LLM budget and was then rejected. The script shape rule required a title to be written out as “Pepper No. 30”, and then the name check and the fact-checker both refused “Pepper Number 30”. The runtime cap of 30 to 40 s also forced drafts down to 53 words. Widening the runtime to 40 to 60 s and reconciling the rules fixed it. With several independent validators, you need a test that they can all pass together.
• Captions under the Subscribe button. The first upload’s captions sat under the Shorts UI. The safe zone was measured again: 240 px at the top, 440 px at the bottom, and a 220 px rail on the right.
• The wrong cover. Remotion shallow-merges --props over defaultProps, so the first unattended video inherited an older video’s cover. Input props are now validated in calculateMetadata.
• A budget that’s enforced in code. LLM calls are capped per day for this project and across it and a sibling pipeline (shorts-engine). A subject has a fixed per-story call budget. Autopilot defers work instead of overspending.

Takeaways 💡

• Ground the model, then check the grounding in code. Every step that uses an LLM (verdict, write, check, hook) is followed by a code audit of what the model claims to have found. A quote that isn’t verbatim is a failure, however confident the model sounds.
• Fail closed where being wrong hurts people. An article that doesn’t clearly say a court closed the case is refused. Losing a good story costs nothing compared with covering an innocent person.
• Pin your sources. A revision id turns “the article said so” into something you can check later.
• Measure what the viewer experiences. The hook passed on paper and failed in the ear. The fixes came from measuring the audio, not from rereading the script.
• AI agents made this possible in three days, and the rules made it safe. The agents built what I specified quickly and with thorough tests. The judgement about what must never be published was the part I couldn’t hand off.

Pact is a small PWA for group habit challenges. Friends join a group with a six character PIN, agree on five daily habits, and compete on a leaderboard that updates live while everyone checks in. A done habit is one point, and finishing all of your habits for the day adds a one point “perfect day” bonus.

The first commit and the tenth merged PR are about 25 hours apart. I did not write most of that code by hand. I directed autonomous AI coding agents (Claude Opus 5 worker agents, run and supervised by firstmate, an open source orchestrator for a crew of coding agents). I made the product calls, reviewed the PRs, and tested on the live app myself. Every feature and fix commit carries a Co-authored-by: Claude Opus 5 trailer. This post covers the design decisions that held up and the bugs that got through anyway.

“Vibe coding” is a fair label for how the code got typed. It is not a fair label for how it got checked. Every PR had to pass unit tests, database tests against the real migrations, and Playwright end to end runs, both against a local stand-in and against a real Supabase stack.

How it fits together 🧭

A group goes through setup once per challenge, then plays the same loop every day: check in, update the ledger, and refresh everyone’s leaderboard. Switch the habit mode to see how shared and personal challenges pick their habits, and select a step for the detail.

Stack 🧰

• Frontend: React 19, Vite 8, TypeScript 6 and React Router. TanStack Query holds all server state; there is no Redux or Zustand. Styling is one token based CSS file (no Tailwind).
• PWA: vite-plugin-pwa with injectManifest and a hand written service worker. It precaches only the app shell. Data always comes from Supabase over the network and is never served from the cache. Updates use registerType: 'prompt', so a new version never swaps in under someone mid check-in.
• Backend: Supabase: Postgres, Auth (email OTP plus guest sign-in) and Realtime.
• Hosting: Vercel, git connected. main deploys to production and every PR gets a preview. vercel.json sets a strict CSP (script-src 'self', worker-src 'self', and connect-src limited to the Supabase host). That CSP comes back later as a bug.
• Tests: Vitest with two projects. One runs unit tests in jsdom pinned to TZ=UTC. The other runs the real SQL migrations on PGlite, an in-process Postgres. Playwright covers the end to end flows.

All the rules live in Postgres 🐘

The main architectural decision is that the client is dumb. Every business rule is a Postgres function, every function is security definer with search_path = '', and the platform migration takes every write path away from the client before granting the RPCs back one by one:

revoke insert, update, delete, truncate on all tables in schema public from anon, authenticated;
revoke all on all tables in schema public from anon;
-- Private bookkeeping tables are not readable at all.
revoke all on public.pin_attempts from authenticated;
revoke execute on all functions in schema public from public, anon, authenticated;
-- ...then each RPC is granted by name
alter default privileges in schema public revoke execute on functions from public, anon, authenticated;

The last line matters most: a function added in a later migration is not callable until someone grants it on purpose. RLS policies are all select only, scoped through helpers like my_group_ids(). The app reads through RPCs anyway, but the policies still matter because Supabase Realtime applies them to postgres_changes.

This made the AI assisted workflow much safer. An agent editing a React component cannot give out points by mistake, because the browser has no write path to the points.

PIN joins

Groups are joined with a code like K7QX3M. The column check is ^[2-9A-HJKMNP-Z]{6}$: 31 symbols with the look-alikes (0/O, 1/I/L) removed, which is about 887 million codes. On a collision, create_group retries the insert on unique_violation. Guessing is rate limited to 10 misses per user per 15 minutes. The miss is recorded instead of raised, so the attempt row still commits:

if (select count(*) from public.pin_attempts
    where user_id = v_uid and not succeeded
      and attempted_at > now() - interval '15 minutes') >= 10 then
  raise exception 'pin_rate_limited';
end if;

The generator does get_byte % 31 on random bytes. 256 is not a multiple of 31, so the first eight characters of the alphabet come up slightly more often. It doesn’t matter at this scale, but it’s worth knowing before quoting an entropy figure.

Points are a ledger, never a total 📒

The leaderboard is always sum(points) over an append-only ledger_entries table. A trigger rejects updates. Undoing a check-in or losing a dispute is just another entry with negative points. That makes every score auditable and every change reversible.

The core is reconcile_day_points(). It never adds points directly. It works out what the member should have for that day, compares that with what the ledger does have, and appends the difference:

v_want_habit := v_done * public.points_per_habit();
v_want_bonus := case when v_slots > 0 and v_done = v_slots
                     then public.perfect_day_bonus() else 0 end;
if v_want_bonus <> v_have_bonus then
  insert into public.ledger_entries (..., points, reason, ...)
  values (..., v_want_bonus - v_have_bonus,
    case when v_want_bonus > v_have_bonus then 'perfect_day'
         else 'perfect_day_lost' end, ...);

A per-member-per-day advisory lock serialises concurrent check-ins, so two taps at once can’t both see “4 of 5 done” and both award the bonus.

Streaks are computed rather than stored, with the classic gaps-and-islands trick. Subtracting a row number from each perfect day’s date gives every consecutive run the same group key:

islands as (
  select pf.user_id, pf.day,
         pf.day - (row_number() over (partition by pf.user_id order by pf.day))::int as grp
  from perfect pf
)

Ties on points are broken by verified_share, the share of your check-ins backed by something stronger than the honor system. previous_rank is the same query restricted to ledger rows before today, which drives the “moved up since yesterday” arrow.

Challenge phases (proposing, voting, upcoming, active, finished) aren’t stored either. A case over the timestamps derives them from now(). Every read RPC calls sync_challenge() first. A pg_cron job runs every minute as a backstop, but nothing depends on it, which is why the whole schema still loads on PGlite, where there is no cron.

Two habit modes in one schema 🗳️

Pact started with one mode. Each member proposes up to five ideas, everyone casts a ballot of up to five picks, and the top five become the group’s habits. Vote totals stay hidden until voting closes so nobody bandwagons. Ties go to the earliest proposal (row_number() over (order by votes desc, seq)). Voting closes at the deadline, or early once everyone has voted.

Voting is fun, but it assumes the group wants the same habits. Plenty of groups want to compete while each person works on their own things. So PR #7 added a personal mode, where each member picks their own five and there is no vote.

The tempting version is a second set of tables. What shipped is one table with a nullable owner:

• A shared habit is a challenge_habits row with user_id null, a candidate_id and a vote count.
• A personal habit is the same row with user_id set.
• A check constraint (challenge_habits_origin) enforces which fields each kind must have, and partial unique indexes keep the two kinds of slot apart.
• A personal challenge is created already resolved, with no voting deadlines, and another check constraint ties habit_mode to that schedule.

Check-ins, timers, spot-checks, disputes and the ledger needed no mode-specific code at all. The one rule that makes it fair lives in member_habit_count(challenge, user). Every scoring query counts your habits, never the challenge’s. The project’s AGENTS.md states it plainly for future agent sessions: “never count a challenge’s habits without the member.” Personal members can’t check in until they have filled all five slots (habits_incomplete). So in both modes everyone plays for the same maximum points per day.

The live leaderboard ⚡

useLive opens one Realtime channel per challenge and listens to postgres_changes on the tables that affect scores, filtered by challenge_id. It doesn’t use Presence or Broadcast.

The important part is what the client does with an event: nothing clever. It never applies row payloads. Any event triggers a debounced (250 ms) invalidateQueries on the ['challenge', id] key prefix, and TanStack Query refetches get_leaderboard. The ledger stays the only source of truth, and a flood of events from five people checking in at once collapses into one refetch.

For the cases where the websocket isn’t there:

• It refetches on every SUBSCRIBED, to catch up after a reconnect.
• It polls every 20 seconds whenever the channel isn’t joined, and shows a “polling” status.
• It refreshes when the tab becomes visible again.

The only optimistic update is the tick on your own check-in. Points and ranks are never guessed on the client.

Days are calendar dates in the challenge’s IANA time zone, which is validated against pg_timezone_names. A day stays open for late logging until 10:00 the next morning (late_log_grace()). A timed habit counts for the day it was started. Countdowns in the browser correct for clock skew using the server_now returned by get_challenge.

Keeping the honor system honest 🕵️

• Random spot-checks. After a done check-in, Pact may ask a question like “Share a detail only someone who did it would know” with a 15 minute window. There is at most one per member per day. The per-check-in chance is solved so a member who completes everything is checked on spot_checks_per_week / 7 of their days: 1 - (1 - rate)^(1 / slots). Answering changes no points. The counts show on the leaderboard, and there is an “Open book” award at the end.
• Timed habits. The server records when a timer starts. complete_timed_session requires the server’s wall-clock time since the start to be at least the target, and the client’s reported active time to be at least the target and no more than the elapsed time plus 2 seconds. The client only counts foreground time: performance.now() deltas on a 250 ms tick, reset on visibilitychange, with a cap per tick so a suspended tab can’t bank time.
• Flags and disputes. Each member gets 3 anonymous flags per rolling week. Flagging an honor check-in only triggers an extra spot-check. Flagging a timed one opens a dispute: the accused has 12 hours to respond, then everyone else votes anonymously. A quorum of half the group is required, and the check-in is voided only if “fake” votes outnumber “legit”. Anonymity comes from RLS: the flags and dispute_votes tables are only readable by whoever wrote the row.

Bugs that got through anyway 🐛

The tests were thorough, and bugs still showed up within hours of the first deploy, found by clicking through the live app. Each of these is a lesson about where the tests weren’t looking.

A one person group voted itself into tracking (#3). I created a group alone, proposed five ideas and voted. “Everyone has voted” was true with one member, so the challenge resolved instantly. Fifty seconds later a second account joined a challenge that was already in the tracking phase, with no vote to cast. The fix was challenge_min_voters() = 2 for opening and closing voting early. The PR also added three SQL tests that fail without the change, and a Playwright spec that replays the exact sequence.

Production sign-in was unreachable (#5). Signing in to the live app ended in “Something went wrong”. The edge logs showed six 429s from /auth/v1/otp and not a single POST to /auth/v1/verify. Three problems had stacked up:

• The hosted project issued 8-digit codes, but the input had maxLength={6}, which silently cut off the emailed code.
• Supabase Auth reports failures on error.code, not in the message, so every auth error fell through to the generic text.
• No test covered email sign-in, because every e2e journey started with “Continue as guest”.

The lasting lesson is from the commit message: a hosted project’s auth settings are “a second source of truth that nothing in the repo checks”. Both sides now match the committed supabase/config.toml, and the local Supabase stand-in can simulate a project’s OTP length and email budget.

A challenge couldn’t start today (#4). Both the date picker and the server required voting to close before day 1’s midnight, which is already in the past for a same-day start. The rule now is that voting must close before day 1 is over, and day 1 is logged retroactively inside the late-log window.

The perfect day confetti was blank in production (#9). canvas-confetti draws in a blob: web worker by default, and the production CSP says worker-src 'self'. Locally it was fine; on the live site the canvas stayed empty. It now draws on the main thread, and the e2e spec applies the same CSP directive and asserts that pixels actually appear.

Testing the real thing 🧪

Two parts of the test setup did most of the work:

1. Real migrations on PGlite. The db Vitest project runs every migration on an in-process Postgres, so about 60 database tests exercise the actual SQL (triggers, RLS, advisory locks) with no Docker.
2. A local Supabase stand-in. local/server.mjs (about 1.1k lines) serves Auth, /rest/v1/rpc and Realtime postgres_changes on top of PGlite. Playwright runs against it on every PR, and a second CI job runs the same suite against a real supabase start stack, which is how RLS and Realtime behaviour gets checked for real.

tests/e2e/live-leaderboard.spec.ts shows the idea. Two browsers check in, the spec watches websocket framereceived events, and it asserts that the viewer’s leaderboard changed without a reload or navigation, in both habit modes.

In total that’s about 19k lines: 10k of TypeScript and CSS, 3.9k of SQL across eight migrations, 3.6k of tests, and around 130 unit, database and end to end tests.

Takeaways 💡

• Put the rules where the agent can’t route around them. With every write going through a granted RPC, and points kept as an append-only ledger, a UI change has no way to corrupt the scores.
• Derive what you can instead of storing it: totals, streaks, phases and ranks. There’s less state to go out of sync, and less for an agent to forget to update.
• Your tests only cover what they can see. Hosted auth settings, a production CSP and a group of one were all outside the test environment until a bug put them in it. Each of those fixes brought that part of production into the tests.
• AI agents move fast, and the review and test gates are what make the speed safe. A day of directed agent work produced a working, deployed app, but only because each PR had to prove itself first.

Try it: pact-deploy.vercel.app

shorts-engine takes long-form video (podcasts, interviews, streams) and turns it into vertical 9:16 shorts with word-timed captions. It finds the moments worth clipping, frames the active speaker, cuts between wide and close shots, burns in captions, and publishes on a daily schedule without me touching it. It runs on a single 16 GB Mac mini.

It is also the biggest thing I’ve built by directing AI agents instead of typing the code. The repo has 157 commits over 11 days, with about 50k lines of Python in the package and 38k lines of tests (1,791 test functions). 134 of those commits carry a Co-authored-by: Claude trailer: mostly Sonnet 5, with Opus 5 and Fable 5.1 on the rest. My job was the one agents are worst at: watching the output and saying “no, that clip is boring”, “that flash has no sound”, “why is there 30 seconds of silence at the end?”.

The repo’s AGENTS.md is the project’s memory. It’s written as dated incident notes (symptom, root cause, fix, tests) so the next agent session doesn’t repeat the last one’s mistake. It is now 5,000+ lines, which says something about both the approach and its cost.

The pipeline 🏭

Here is the whole flow, from a source video to an upload. Select a stage to see what it does, or press Play to follow one clip through it. The dashed lines are the two loops: a clip that scores too low goes back to be re-rendered, and the shelf pulls in new sources as it empties.

Curation runs before vision on purpose. Early on, vision ran first and scanned the whole 40 minute source for faces. Moving it after curation, so it only looks at the chosen windows, took the vision stage from 746 s to 23 s and a full run from about 30 minutes to 18.

1. Ingest 📥

• Downloads with yt-dlp.
• Extracts 16 kHz mono audio and normalises it to -16 LUFS (EBU R128).
• Detects scene cuts, which the framing stage uses later.

2. Transcription 🎙️

• Uses faster-whisper with large-v3-turbo and word timestamps on.
• Snaps each word’s timing to a 20 ms energy envelope, so a caption appears when the word is actually heard. Overlapping words are split at the quietest frame.
• Diarization uses pyannote when it’s installed and a heuristic acoustic diarizer otherwise.
• Results are cached by the audio’s hash, so a re-run doesn’t redo a 3 hour transcription.

3. Curation: an LLM that reads the whole transcript 🧠

The default curator is one Gemini call that sees the whole transcript as numbered sentences. Each sentence is tagged with acoustic cues computed locally: an energy percentile plus LOUD, SPIKE, REACT and FAST flags. On a stream, a shout or a burst of laughter is often the best clue that something clip-worthy just happened, and text alone doesn’t show that.

The model returns up to five ranked moments. Each has a title, a hook line, hashtags, 0 to 100 scores for hook, payoff and loop strength, and the sentence ranges to keep. The prompt tells the model outright that duration limits are enforced in code after it responds, and they are. A clip may not open on a greeting, filler or a sentence fragment. The default profile targets 15 s clips, within 10 to 25 s.

If the model is unavailable, the fallbacks are loud:

1. A sliding-window segmenter builds candidates (about 8,500 on a 3.5 hour source) and scores them with rules.
2. Batches of up to 150 candidates go to Gemini.
3. If that fails, a local Ollama qwen3:8b curates.
4. If that fails too, the rule-based score is used on its own.

There is a hard floor, min_acceptable_curator_backend="local_llm", so a clip picked by rules alone is never published. Cloud calls are capped at 30 a day and tracked in a spend ledger. A local YAMNet classifier flags clips with too much copyrighted music.

4. Vision and framing 🎯

All of this runs locally:

• Faces: YuNet (a 232 KB OpenCV ONNX model), falling back to MediaPipe BlazeFace, then Haar cascades.
• Active speaker: mouth movement from face-mesh landmarks, correlated with word timing and audio RMS, then bound to the diarized speakers.
• Layout: the director chooses per shot between single_speaker, dual_split and wide_letterbox. The crop path is smoothed with Kalman and Bezier filters so it never jitters.
• Pacing: it alternates wide shots and punch-ins, each 1.8 to 6 s long, on speaker changes and emphasis. Punch-ins require enough confidence. When it isn’t sure who is talking, it stays wide rather than zooming in on the wrong person.

5. Render 🎬

Rendering is plain FFmpeg filtergraphs, not a browser renderer:

• Captions are ASS subtitles burned in with the ass= filter, in five bundled OFL fonts.
• Dead air is removed with jump cuts: any gap between words over 350 ms shrinks to 120 ms, using select/aselect plus setpts.
• It adds a 1 to 5 s “flash-forward” cold open that teases the payoff, a CC0 music bed, meme sound effects and profanity bleeps.
• Encoding uses h264_videotoolbox on the Mac, falling back to NVENC, then libx264.

6. The watchability judge 👀

Curation guesses from text. The watchability judge checks the finished clip. A 360p, 24 fps proxy goes to Gemini, which answers four questions that can be checked:

• Does it open without needing context?
• Is there a reason to keep watching?
• Does the payoff land?
• At what second would a viewer drop off?

Then it gives one watchability_score. The prompt asks for it “calibrated like a real retention percentage”, not a virality guess.

At first the judge only logged a prediction (accept at 55 or above). Now it closes the loop. Below a target of 70, the pipeline repairs the clip by extending the start or end, or swaps in a reserve candidate, and asks again. It is capped at 2 attempts per clip and 10 judge calls per source, and costs about $0.002 to $0.003 per clip.

7. Autopilot and publishing 📅

There is no custom daemon. autopilot is a set of CLI verbs (discover, fill-shelf, publish-slot, status, cleanup) run by macOS launchd:

• Discovery runs nightly and checks tracked channels for new uploads. It uses the 1-unit playlistItems and videos.list calls, not the 100-unit search.list, to stay inside the YouTube API quota.
• Fill-shelf runs every 4 hours and keeps a shelf of about 10 rendered, judged clips ready.
• Publish-slot fires five times a day and uploads the next clip with a resumable upload. It reads the privacy status back from the API instead of assuming it. English sources publish publicly; everything else stays private.

War stories 🔥

The best way to understand a system is through what broke in production. These are the ones I found most interesting.

Two schedulers, one clip, two uploads

On 17 September the same clip went up twice at 18:00, and again at 20:00.

That afternoon both launchd flavours had been installed: a LaunchAgent (a per-user job) at 16:30 and a LaunchDaemon (system-wide) two minutes later. So every publish slot started two publish-slot processes in the same second. There was a lock, but it was the classic check-then-act kind:

if lock_path.exists():
    existing_pid = int(lock_path.read_text(...).strip())
    if existing_pid > 0 and _pid_is_alive(existing_pid):
        raise LockHeld(...)
lock_path.write_text(str(os.getpid()), encoding="utf-8")

Two processes starting together both see no live pid, both write their own, and both upload. The fix is to let the kernel decide:

fd = os.open(str(lock_path), os.O_RDWR | os.O_CREAT, 0o644)
try:
    fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
except OSError as exc:
    os.close(fd)
    ...
    raise LockHeld(f"{name} is already running (pid {holder}, lock {lock_path})") from exc

flock is atomic, and the kernel releases it when the holder exits or is killed, so a crash leaves no stale lock to clean up. The subtle part is that the lock file is never unlinked. Deleting it on release brings the race back in a new form: one process opens the old inode just before the unlink and locks it, a third process creates a new file at the same path and locks that, and both run.

The rest of the fix was operational. The daemon installer now removes the LaunchAgents, the agent installer refuses to run while the daemons exist, and autopilot status flags more than one installed publish job. The regression tests race real OS processes: 6 contenders for the lock (the old lock failed 5 out of 5 rounds) and 4 publish-slot processes on one shelf (the old code uploaded the clip up to 4 times; now it’s exactly once).

This was actually the second duplicate-upload bug. The first was a lookup by clip_id alone. clip_001 is only unique within one source video, so publishing marked the wrong source’s row as published, the real row stayed due, and the next tick uploaded the file again. The fix matches on (pool_video_id, clip_id) and raises on any ambiguous match. Before any retry, a separate crash-safety layer also checks the channel’s real uploads for a matching title.

The phantom track: 30 seconds of silence from a music file

Some renders played 22 to 25 seconds of real content, then dead air until 48 to 60 seconds. Other clips from the same run were fine.

ffprobe showed nothing wrong at first: the video stream, audio stream and format.duration were all correct. But the file had a third stream: codec_tag=text, SubtitleHandler, one frame, about 50 seconds long. macOS QuickTime and Finder take the longest track as the file’s length.

That third stream turned out to be chapters. FFmpeg’s -map_chapters defaults to copying chapters from the first input that has any, and explicit -map flags don’t affect it because chapters aren’t a stream. The mov muxer then writes them out as a text track. Two of the 46 bundled CC0 music beds had a leftover Tempo: 120.0 chapter spanning 0 to 75.007 s, from whatever tool had cut them. The music rotation starts each bed at a random offset, so only clips that drew one of those two tracks got a phantom track, with a length of 75.007 s minus the offset.

The fix is three flags on every output:

CONTAINER_HYGIENE_FLAGS = [
    "-map_chapters", "-1",
    "-dn",
    "-sn",
]

-map_chapters -1 is the real fix; -dn and -sn (drop data and subtitle streams) are defence in depth. There’s also a read-back gate: every render must contain exactly one video and one audio stream, with durations within 0.5 s of each other. The lesson I keep coming back to is that a container-vs-video duration check would not have caught this, because those two agreed. Only a per-stream check could.

Kernel panics on a 16 GB Mac

The Mac mini had three watchdog kernel panics in about 18 hours. The Whisper model stayed loaded through later stages and could overlap with Ollama, which was measured at 6.6 GB resident while idle, leaving about 0.5 GB free. FFmpeg had no thread cap either.

The fix:

• Release the ASR engine as soon as transcription finishes.
• Unload Ollama with keep_alive=0.
• Cap FFmpeg at 4 threads.
• Add ensure_stage_headroom, which refuses to start a stage without enough free memory.

For a pipeline that runs unattended, failing to start is much better than taking the whole machine down.

launchd has no login shell

The overnight run had no Gemini key, because launchd doesn’t source your shell profile. The fallback chain quietly shelved clips picked by the rule-based scorer. The log even printed a key source, because it rendered the environment variable’s name unconditionally.

The fix:

• A small env shim resolves the key at run time. It is never written into the world-readable plist.
• The min_acceptable_curator_backend floor, so a degraded curator can never feed the publish queue again.

The same PR fixed a shelf write race, where every writer staged through the same .tmp file. Each read-modify-write now happens under a blocking flock.

LLM reasoning leaked into public descriptions

The whole-transcript curator set headline = reasoning[:200]. So two public videos went out with descriptions that referred to “Sentence 141”, with an unmasked swear word included. It was an easy fix and a good reminder: anything a model writes for you has to be kept apart from anything it writes for the audience.

Flashes with no sound

I rejected a batch where one clip had 7 visual flashes and 1 sound effect, because flashes and sounds were scheduled independently. The fix turned the relationship around: a flash can only exist at the onset of a validated sound, and enforce_flash_sound_invariant strips any orphan. Encode an aesthetic rule as an invariant, not a tuning knob.

What directing agents at this scale taught me 💡

• Taste doesn’t delegate. Agents wrote well-tested code for every rule I stated. Almost every bug that reached production was a rule nobody had stated yet: no silent tail, no flash without a sound, no clip picked by rules alone.
• Make the agents write down every incident. The dated sections in AGENTS.md are why later sessions knew not to re-cut the music files (their SHA-256 hashes are pinned for licence credits) or unlink a lock file.
• Prefer invariants checked on the output. Stream counts, flash/sound pairing and the curator floor are all checked on what actually gets produced, not on what the code meant to do.
• Races are the same in hobby projects. Two schedulers and a check-then-act lock is a distributed systems bug on a single Mac mini. flock, idempotent reconciliation and tests that race real processes fixed it, as they would anywhere.

This documentation gives the details of steps to be followed for configuring self hosted agents for Azure pipelines.

Pre-requisite 🚧

• Already have Azure pipeline account / organization.
• WSL Ubuntu is installed in your windows machine or using Ubuntu out of the box to be used as self-hosted agent.

Setup Instructions 🚧

• Login to Azure devOps portal here
• Goto organization settings present on the bottom left.
• Goto pipelines –> Agent pools –> Click Default and New Agent.
• Click on the Linux tab from the options, as in my case I want to install the agent in my WSL Ubuntu system.
• Click on Download the agent, it will download (current version)

    vsts-agent-linux-x64-3.238.0.tar.gz
  

• Move the downloaded archive to /tmp folder, in my case it was downloaded under /mnt/h/downloads

    mkdir -p ~/tmp
    mv /mnt/h/downloads/vsts-agent-linux-x64-3.238.0.tar.gz ~/tmp
  

• Follow the instructions on the tab (under Linux)

     cd ~
     mkdir myagent && cd myagent
     tar zxvf ~/tmp/vsts-agent-linux-x64-3.238.0.tar.gz
  

• Create PAT token from your Azure pipeline Organization following the below screenshots.

  Don’t forget to keep the copy of PAT token somewhere securely in your system.

  

• Go back to the Ubuntu command line and run the configuration script.

  Once you run configuration it will prompt for PAT token and other details like Agent-name and Agent-pool etc, give any name but keep it default for other options.

    #Server URL: https://dev.azure.com/{your-organization}
    cd ~/myagent
    ./config.sh
  

• That’s it now you should see the agent under your Default Agent pool but in offline state.
• Now you can start the agent using the run script.

    cd ~/myagent
    ./run.sh
  

• That’s it now you have your own agent running, you can use this to build artifacts, in my case I wanted to build npm project, so installed npm

    sudo apt install npm
  

• Try building the project with Azure pipelines, with pool configured as default. example:

    trigger: 
    - main
  
    pool: 
    name: default
    stages:
    - stage: "Build_stage"
    jobs:
    - job: "Build"
        steps:
        - task: Npm@1
        inputs:
            command: 'install'
  

• Now try running the build manual using the run button of the pipeline and check the status of the build in your agent run session.
• Congratulations, you have configured your own self-hosted runner for builds.

  Resources 📚

• Azures Docs

This documentation talks about the various commands that are used as part of Linux administration in day 2 day activities.

Pre-requisite Setup Instructions 🚧

Download Oracle VM Virtual Box from Click here.
Download RedHat Linux ISO Click here.

Important Commands ⌨️

• Adding a User
  • Add Operation

      useradd ant
    

  • Verification, check if a folder ant is created in the /home directory

      cd /home/
      ls ant
    

• Adding a Group
  • Add Operation

      groupadd insects
    

  • Verification, check if an entry is present in /etc/group file

      cat /etc/group | grep insects
    

• Assigning User to Group
  • Modify User

      usermod -G insects ant
    

  • Verify if User is added to the Group

      cat /etc/group | grep insects
      #insects:x:1004:ant
      #group:encryptedpasswd:groupid:userid
    

• Checking Different files under /etc
  • passwd [UserFile]

      cat /etc/passwd | grep ant
      #ant:x:1002:1003::/home/ant:/bin/bash
      #user:encryptedpasswd:userid:groupid:homedirectory:shell
    

  • group [GroupFile]

      cat /etc/group | grep ant
      #insects:x:1004:ant
      #group:encryptedpasswd:groupid:userid
    

  • shadow [PasswordFile]

      cat /etc/shadow | grep ant
      #ant:!!:19835:0:99999:7:::
    

• One line command to create the User and Assign it to a Group
  • Create User and add to Group

          useradd -G insects -s /bin/bash -c "This is a bug" -m -d /home/bug bug
          # -G GROUP
          # -s SHELL
          # -c COMMENT
          # -m CREATE HOME DIRECTORY
          # -d HOME DIRECTORY
    

  • Create password for the User

      passwd bug
    

  • Verification

      cat /etc/shadow | grep bug
      #bug:$6$tipJYGx11g3arh2U$R7nEyhEIy90wDEtPf32Zr4T0EWHVtcrH6I6h1Nd8IpRbrHd1v4mc1Mbn4XY2A.If/OuCnW.BPshjbOLL1uIMv1:19835:0:99999:7:::
      #This is an encrypted password in shadow file
    
      cat /etc/passwd | grep bug
      #bug:x:1003:1005:This is bug:/home/bug:/bin/bash
    
      cat /etc/group | grep bug
      #insects:x:1004:ant,bug
    

• Delete User, Group
  • User

      userdel -r ant
      #Remove home directory as well
      groupdel insects
    

• Changing Password policy
  • Per User

      chage -m mindays -M maxdays -d lastday -I inactive -E expiredate -W warndays user
      #bug:$6$tipJYGx11g3arh2U$R7nEyhEIy90wDEtPf32Zr4T0EWHVtcrH6I6h1Nd8IpRbrHd1v4mc1Mbn4XY2A.If/OuCnW.BPshjbOLL1uIMv1:19835:0:99999:7:::
    
      #So from the above let's consider the following 19835:0:99999:7::: 
      # -d lastday: days since 1 Jan 1970 the password was change so we see 19835 days (April 22, 2024).
      # -m mindays: After how many days can a user change the password, currently no restriction hence 0, if set to 5, the User can change password after 5 days.
      # -M maxdays: After how many days User should be prompted to change password, Current is 99999 that is alot, hence we have to change it to something meaningful.
      # -W warning: Warn User when password is going to expire.
      # -I Inactive: Set User as inactive after number of days Password expires.
      # -E Expire: Days after which the User to expire from 1 Jan 1970.
    
      #Let's apply this to the user bug using chage
      chage bug -m 5 -M 90 -W 10 -I 3 
      #bug:$6$tipJYGx11g3arh2U$R7nEyhEIy90wDEtPf32Zr4T0EWHVtcrH6I6h1Nd8IpRbrHd1v4mc1Mbn4XY2A.If/OuCnW.BPshjbOLL1uIMv1:19835:5:90:10:3::
    

  • All Users

      cat /etc/login.defs
      #PASS_MAX_DAYS   99999
      #PASS_MIN_DAYS   0
      #PASS_MIN_LEN    5
      #PASS_WARN_AGE   7
      #UMASK 077
    

• Sudo Commands
  • Switch User to root

      su
      #Prompts for root password
    

  • Switch User to bug

      su bug
    

  • Add users to sudoer group using wheel Group to execute certain commands like dmidecode which are accessible only to root

      usermod -aG wheel smore
    
      #Test using the sudo command
      sudo dmidecode
      sudo fdisk -l
    

• Other important commands - Monitoring and Manage processes

  • Filesystem Usage

    df -h
    #h is human readable format
    

  • Disk Usage

    du -h
    #Details of each file in the filesystem
    

  • Check system uptime

    uptime
    #Gives basic information like since when is the system up and running etc.
    

  • Checking processes running in server

    top
    

  • Check the swap and memory

    free
    

  • Check list of open files

    lsof
    

  • Networking command, incoming network

    tcpdump -i enp0s3
    

  • Network statistics using netstat

    netstat
    

  • Check processes runnning using ps -ef

    ps -ef | grep java
    

  • Force kill a process using kill command

    kill -9 47474
    

• Controlling Services and daemons using systemctl
  • Get all the services running

    systemctl --all
    

  • Check a particular service status

    systemctl status firewalld.service
    

  • Stop the service - i.e. it will change the status to inactive

    systemctl stop firewalld.service
    

  • Restarting the firewall service

    systemctl restart firewalld.service
    

  • Reload the cofiguration of the service

    systemctl reload firewalld.service
    #Reload the config without impacting the service
    

  • Configure the service to start during linux start time and vice-versa

    systemctl enable firewalld.service
    #This will add the service to start at restart
    systemctl disable firewalld.service
    #This will remove from the startup list
    

  • Prevent accidental starts of the service by masking the service

    systemctl mask firewalld.service
    #The service is masked now you wont be able to start it until it is unmasked.
    systemctl unmask firewallId.service
    

• Secure SSH login using keys
  • If Machine A wants to login to Machine B without providing username/password.
    • Generate the key pair in Machine A

      ssh-keygen
      #Enter password if you want to else you can ignore
      cd /home/usera/.ssh
      #You will find two new files, id_rsa.pub [public key] and id_rsa [private key], copy the public key
      

    • Copy the public key of the USER ONE from Machine A to Machine B USER TWO’s authorized_keys file

      cd /home/userb/.ssh
      #Login to server B, as USET TWO
      vi authorized_keys
      #Create a new file if not present and paste the content of public key copied in the above step
      

      

Resources 📚

• RedHat Doc

There are instances where EKS Pods needs access to AWS services like S3, this tutorial talks about the different services like serviceaccounts, OIDC provider, IAM roles/policies and STS used to accomplish this goal.

Overview 📝

Setup Instructions 🚧

• Create a dummy S3 bucket in your specific region, I am creating it in ca-central-1.

    aws s3api create-bucket \
    --bucket my-bucket-dummy-eks \
    --region ca-central-1 \
    --create-bucket-configuration LocationConstraint=ca-central-1
  

• Create the EKS cluster using the below command which has EC2 nodes as cluster nodes. (It takes approximately 15 minutes for the cluster creation)

    eksctl create cluster --name demo-s3-cluster --region ca-central-1 --with-oidc --nodes 2 --instance-types=t2.micro
  

• Once cluster is created, run a kubectl command to get nodes, you should see the EC2 nodes.

    kubectl get nodes -o=wide
  

• Let’s create the OIDC provider, policies and roles from the console for the EKS cluster (Note: by default it will be create if you use the above EKS creation command)
  • Go to the EKS console and get the OIDC provider URL of the cluster
  • Configuring the OIDC provider using IAM console (IAM console > Access Management > Identity Providers > Add providers)
  • Create policy to grant access to S3 buckets (IAM console > Access Management > Policies ), I have named it as pod-access-to-s3.

      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Sid": "VisualEditor0",
                  "Effect": "Allow",
                  "Action": [
                      "s3:ListBucket",
                      "s3:ListAllMyBuckets"
                  ],
                  "Resource": "*"
              }
          ]
      }
    

  • Create a role and attach the policy created above to it, create the role as per below screenshot
    • Make sure that the trusted policy is as mentioned below, it includes the service account name (which we are yet to create) and the OIDC ID which was created above

        {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Principal": {
                    "Federated": "arn:aws:iam::<<ACCOUNTID>>:oidc-provider/oidc.eks.ca-central-1.amazonaws.com/id/<<OIDC ID>>"
                },
                "Action": "sts:AssumeRoleWithWebIdentity",
                "Condition": {
                    "StringEquals": {
                        "oidc.eks.ca-central-1.amazonaws.com/id/<<OIDC ID>>:aud": "sts.amazonaws.com",
                        "oidc.eks.ca-central-1.amazonaws.com/id/<<OIDC ID>>:sub": "system:serviceaccount:<<NAME SPACE>>:<<SERVICE-ACCOUNT>>"
                    }
                }
            }
        ]
        }        
      

• Let’s create a pod and service account attached to it in the default namespace.
  • Service account needs to be annotated with the role that we have created above:

      apiVersion: v1
      kind: ServiceAccount
      metadata:
      annotations:
          eks.amazonaws.com/role-arn: 
                  arn:aws:iam::891377161155:role/pod-access-s3-role
      name: sa-access-s3
      namespace: default
    

  • Create a Pod which will use the above service account.

      apiVersion: v1
      kind: Pod
      metadata:
      creationTimestamp: null
      labels:
              run: access-s3-pod
      name: access-s3-pod
      spec:
      containers:
      - args:
              - help
      image: amazon/aws-cli
      name: access-s3-pod
      serviceAccount: sa-access-s3
    

  • Once the pod is create run the below command to make sure that the Pod has the web identity token file mount.

      kubectl describe pod access-s3-pod | grep AWS_WEB_IDENTITY_TOKEN_FILE:
    
      #Example output
      #AWS_WEB_IDENTITY_TOKEN_FILE:  /var/run/secrets/eks.amazonaws.com/serviceaccount/token
    

    Testing 🧪

• Let’s test and see if the pod can now access the S3 bucket or not.

    kubectl exec -it access-s3-pod -- sh
    #Run the aws s3 ls to list the buckets
    aws s3 ls
    #You will see the buckets that are present in your account
    #2024-04-20 18:28:50 my-bucket-dummy-eks
    #2024-04-20 17:16:38 s3-bucket-eks-demo
  

  Cleanup 🧹

• Make sure to delete the cluster.

    eksctl delete cluster --name demo-s3-cluster
  

  Resources 📚

• AWS EKS

Amazon Elastic Kubernetes Service (EKS) is a managed Kubernetes service that simplifies the deployment, management, and scaling of containerized applications using Kubernetes on AWS infrastructure.

Overview 📝

This project showcases the seamless experience of utilizing Amazon Elastic Kubernetes Service (EKS) by deploying a delightful application game called ‘pod-birds’ 🐦 onto the EKS cluster.

Features ✨

Managed Kubernetes Service: Enjoy the benefits of a fully managed Kubernetes service with Amazon EKS, eliminating the need for manual setup and maintenance of Kubernetes control plane components, enabling you to focus on building and deploying your applications.

Simplified Deployment with kubectl: : Streamline the deployment process of containerized applications with Amazon EKS, using the familiar kubectl command-line tool to interact with your Kubernetes cluster.

Integration with AWS Services: Seamlessly integrate Amazon EKS with other AWS services such as AWS IAM and AWS LB enhancing the overall efficiency and capabilities of your Kubernetes deployment.

Cost Optimization: Optimize your infrastructure costs with Amazon EKS using serverless - Fargate.

High Availability: Ensure high availability for your applications with Amazon EKS, leveraging multi-AZ deployment options.

pre-requisites

• awscli - Command line tool for working with AWS services here
• eksctl - Command line tool for working with EKS clusters here.
• kubectl - Command line tool for working with kubernetes API here.

Setup Instructions 🚧

• Create an access key for your user and from IAM user section better to use user which has admin access.
• Configure the access key in the system using aws cli

    #The below command will prompt for ACCESSKEY and PASSWORD
    aws configure
  

• Now that the aws cli configuration setup is done, let’s create the (fargate) cluster from the command line, this will take sometime:

    eksctl create cluster --name <your-cluster-name> --region <region> --fargate
  

  This creates a VPC by itself with public/private subnet hence we don’t have to manually create it.

• Let’s check if the cluster is created, goto AWS EKS -> Cluster

• Check if the kubeconfig file is having the correct details i.e. it is aws eks context, server settings. Run below to configure kube config.

    aws eks update-kubeconfig --region <region> --name my-cluster
  

• Create fargate profile to attach to the namespace

    eksctl create fargateprofile --cluster <your-cluster-name> --namespace development --name  flying-bird-fargate
  

  If fargate profile is not created, the pods which are supposed to be deployed to development namespace, will not be deployed, it is to link the fargetprofile with the namespace.

• Fargate profile can be verified from the console

• Now Let’s deploy the application, it will create deployment, service and ingress

    curl -O https://raw.githubusercontent.com/erom-teknas/pod-birds/main/bird-pods.yml
    kubectl -f bird-pods.yaml
  

  Note the ingress will not be in effect as we have not deployed the ingress controller, which we will see in below steps.

• Check if the deployment of the bird-pod is done.

    # You should see bird-pod-xx running
    kubectl get pods -n development
  

• Now let’s download the IAM policy provided by aws-loadbalancer-controller.

    curl -O https://raw.githubusercontent.com/kubernetes-sigs/aws-load-balancer-controller/main/docs/install/iam_policy.json
  

• Create the policy using the iam_policy.json

    aws iam create-policy --policy-name AWSLoadBalancerControllerIAMPolicy --policy-document file://iam_policy.json
  

• Create the service account using eksctl for the aws-load-balancer-controller in EKS and a role for it, using the below command.

    eksctl create iamserviceaccount \
    --cluster=<your-cluster-name> \
    --namespace=kube-system \
    --name=aws-load-balancer-controller \
    --role-name AmazonEKSLoadBalancerControllerRole \
    --attach-policy-arn=arn:aws:iam::<your-aws-account-id>:policy/AWSLoadBalancerControllerIAMPolicy \
    --approve
  

• Install the ALB controller in the kube-system namespace for ingress to work.

    helm repo add eks https://aws.github.io/eks-charts
    helm install aws-load-balancer-controller eks/aws-load-balancer-controller \            
    -n kube-system \
    --set clusterName=<your-cluster-name> \
    --set serviceAccount.create=false \
    --set serviceAccount.name=aws-load-balancer-controller \
    --set region=<region> \
    --set vpcId=<your-vpc-id>
  

• Once the ALB controller is installed correctly, the ALB controller will create the ALB load balancer based on the rules set in the ingress object as part of (kubectl -f bird-pods.yaml)

  Testing 🧪

• Verify using the ALB URL if you are able to access the browser

  Resources 📚

• AWS EKS OIDC
• AWS EKS

Git repo 📁

REPO

Seamlessly integrate JIRA with GitHub using our 🔗 integration.

Overview 📝

This project demonstrates a straightforward method to integrate JIRA with GitHub. Any changes made to a JIRA ticket, such as transitioning its status, will automatically trigger GitHub actions.

Features ✨

• Seamless Integration: Effortlessly connect JIRA with GitHub to streamline your workflow.
• Automated Triggering: Automatically trigger GitHub actions in response to any changes made to a JIRA ticket.
• Real-Time Updates: Stay up-to-date with real-time notifications in GitHub when a JIRA ticket’s status is transitioned.
• Enhanced Collaboration: Facilitate collaboration between development and project management teams by integrating JIRA and GitHub seamlessly.
• Efficient Workflow: Simplify your workflow by automating processes and reducing manual interventions between JIRA and GitHub.

Setup Instructions 🚧

• Create PAT token under GITHUB account Goto Profile –> Developer settings –> PAT (with workflow access) and copy the PAT token and store it securely for now.
• Now let’s create the JIRA automation (Requires access to project automation) Goto JIRA project –> settings –> Automation –> Click create Rule (let’s choose when issue is transitioned from in-progress to Done)
• Add the action as send web request.
• Configure the web request URL, the format of the github repository to invoke the workflow is below:

  https://api.github.com/repos/[github-user]/[REPO]/actions/workflows/[WORKFLOW_ID]/dispatches
  

  • How to get the WORKFLOW_ID? hit the below URL in browser and you will get the workflow id

    https://api.github.com/repos/[github-user]/[REPO]/actions/workflows
    

    

• Configure the other settings of the JIRA Automation:
  • Set HTTP Method as POST

  • Web Request body as Custom with the following content (i.e. we are sending JIRA key number to the GITHUB request as my git repo workflow expects input)

      {
      "ref":"main",
      "inputs":{
          "issue_key": "{{ issue.key }}"
          }
      }
    

  • Configure the headers section:

    key	value	Hidden
    Authorization	Bearer «PAT FROM GITHUB»	✅
    Accept	application/vnd.github+json
    X-GitHub-Api-Version	2022-11-28

  • You can test validate by clicking on validate button, however you will need to set the “issue_key” to some hardcoded value, as you are manually triggering the automation.

      "issue_key": "TEST"
    

    you should see status code as 204

    Remember to revert the issue_key, so that actual JIRA key is sent to GITHUB instead of test.

  • Save the automation

Testing 🧪

• Now let’s try to check if our automation is working as expected.
• Create a ticket and move the ticket from in-progress status to Done.
• This will trigger GITHUB-ACTIONS, go to the actions tab to verify.
• The JIRA ticket is present in the GITHUB logs as it was printed

  Resources 📚

• GTHUB PAT AUTHENTICATION

• GITHUB DISPATCH

Git repo 📁

REPO

Happy coding! 🎉

Streamlining infrastructure management with ease and efficiency.

Overview 📝

A collaborative, scalable platform for managing infrastructure as code seamlessly. In this project we will utilize the existing aws single architecture from the existing project, but we will utilize the terraform cloud to create the architecture, the project we will use is GITHUB

Features ✨

• Infrastructure as Code (IaC): Define and manage AWS resources using Terraform configuration files.
• Collaboration: Work with team members on AWS architecture within Terraform Cloud, enabling version control.
• Remote State Management: Store and manage Terraform state files securely in Terraform Cloud.
• Automation: Automate basic provisioning tasks using Terraform Cloud.
• Scalability: Scale AWS deployments efficiently with Terraform Cloud.
• Cost Management: Get basic cost insights for AWS infrastructure through Terraform Cloud.

Setup Instructions 🚧

Following are the steps for configuring and using terraform cloud:

• Checkout Github Repository: Check out the repositories which we are going to use for this project.

  git clone https://github.com/erom-teknas/terraform-aws-simple-architecture.git
  

• Terraform Cloud Signup/Login: Let’s create an account in terraform cloud Terraform Cloud, I am using GitHub credentials to signup to Terraform cloud.
• Terraform CLI login: Once you have created the account, you can login using the cli command, which will prompt you to create a token for login and open browser for the token createion, create token and copy it to the console.

  terraform login
  

  

• Update backend Configuration: Update the backend configuration to use the terraform cloud as backend so that the statefile is saved in it.

#update backend block of the terraform.tf file, make sure that the organization is already created.
terraform {
  backend "remote" {
    hostname = "app.terraform.io"
    organization = "Enterprise-Terraform-Teknas"
    workspaces {
      name = "dev-aws-single-az"
    }
  }

terraform init

• Terraform Plan: Run terraform plan inside the repository to check the behaviour. This will fail with the following error “No Valid credentials source found”

• Configure Credentials: Now as we have changed the backend to remote, our locally configured environment secret variables are not used instead we will have to configure the secrets using the Terraform Cloud console. Goto Organization -> Workspace -> Variables (Add sensitive environment variables)

  • Re-run terraform plan command and this time it will be successful.

    terraform plan
    

    

• Apply the changes: As the plan is now successful, run the terraform apply to apply the change to the AWS account and approve the apply using the UI.

• Miscellenous: Once the changes are applied to AWS account, you will see outputs under the overview section of the workspace.
  • Similarly, you will see the historical runs that have been executed
  • State file stored in the remote
• Destruction: Don’t forget to destroy the AWS architecture, as it might incur cost, using terraform destroy.

  terraform destroy -auto-approve
  

  Resources 📚

• Terraform Cloud

Happy coding! 🎉

Achieve efficient resource allocation and maximize cost-effectiveness in your AWS infrastructure.

Overview 📝

This project provides step by step guide to effectively shutdown the development EC2 instances which are not going to be used after hours and start them during weekdays at 8:00 AM

Features ✨

• Automated EC2 Management: Utilize AWS Lambda functions triggered by Amazon EventBridge to automatically start and stop your EC2 instances at specific times, such as 8:00 am and 6:00 pm.
• Event-Driven Workflow: Set up EventBridge rules to trigger Lambda functions based on scheduled events, enabling seamless automation of EC2 instance management tasks.
• Notification Alerts: Upon successful start and stop actions of EC2 instances, trigger additional events to send notifications to an Amazon SNS topic, keeping stakeholders informed about the status of instance operations.

Setup Instructions 🚧

Following are the steps to setup automated EC2 management system using AWS Lambda, Amazon EventBridge, and Amazon SNS:

• VPC: Let’s create a VPC, with a public, private subnet, a internet gateway and nat gateway.
• EC2 Instances: Create EC2 instances that you want to manage automatically(in private subnet). Note down the instance tags (env:dev) that will be used to identify these instances in your Lambda functions.
• Lambda Functions: Create Lambda functions responsible for starting and stopping EC2 instances. These functions will be triggered by EventBridge rules based on scheduled events.
  • stop-ec2-dev-instance

    import boto3
    def lambda_handler(event, context):
        print("Starting Lambda function execution...")
          
        # Initialize the EC2 client
        print("Initializing EC2 client...")
        ec2_client = boto3.client('ec2')
          
        # Define the tag key-value pair to filter instances
        tag_key = 'env'
        tag_value = 'dev'
          
        try:
            print("Describing EC2 instances with the specified tag...")
            # Describe EC2 instances with the specified tag
            response = ec2_client.describe_instances(
                Filters=[
                    {'Name': 'instance-state-name', 'Values': ['running']},
                    {'Name': f'tag:{tag_key}', 'Values': [tag_value]}
                ]
            )
              
            # Check if there are running instances with the specified tag
            if 'Reservations' in response and len(response['Reservations']) > 0:
                print("Running instances found with the specified tag. Printing details...")
                # Iterate over reservations and stop instances
                for reservation in response['Reservations']:
                    for instance in reservation['Instances']:
                        instance_id = instance['InstanceId']
                        instance_type = instance['InstanceType']
                        private_ip = instance['PrivateIpAddress']
                        print(f"Stopping instance: {instance_id}, Type: {instance_type}, Private IP: {private_ip}")
                        # Stop the instance
                        ec2_client.stop_instances(InstanceIds=[instance_id])
                          
                        # Wait until instance state changes to stopped
                        waiter = ec2_client.get_waiter('instance_stopped')
                        waiter.wait(InstanceIds=[instance_id])
                          
                        print(f"Instance {instance_id} stopped successfully.")
            else:
                print("No running instances found with the specified tag.")
          
        except Exception as e:
            print(f"An error occurred: {e}")
  
        print("Lambda function execution completed.")
  
    # Uncomment the line below for testing locally
    # lambda_handler(None, None)
  

  • start-ec2-dev-instance: Create a lambda function in the same VPC as EC2 and in the private subnet.

    import boto3
    def lambda_handler(event, context):
    print("Starting Lambda function execution...")
      
    # Initialize the EC2 client
    print("Initializing EC2 client...")
    ec2_client = boto3.client('ec2')
      
    # Define the tag key-value pair to filter instances
    tag_key = 'env'
    tag_value = 'dev'
      
    try:
        print("Describing EC2 instances with the specified tag...")
        # Describe EC2 instances with the specified tag
        response = ec2_client.describe_instances(
            Filters=[
                {'Name': 'instance-state-name', 'Values': ['stopped']},
                {'Name': f'tag:{tag_key}', 'Values': [tag_value]}
            ]
        )
          
        # Check if there are stopped instances with the specified tag
        if 'Reservations' in response and len(response['Reservations']) > 0:
            print("Stopped instances found with the specified tag. Printing details...")
            # Iterate over reservations and start instances
            for reservation in response['Reservations']:
                for instance in reservation['Instances']:
                    instance_id = instance['InstanceId']
                    instance_type = instance['InstanceType']
                    private_ip = instance['PrivateIpAddress']
                    print(f"Starting instance: {instance_id}, Type: {instance_type}, Private IP: {private_ip}")
                    # Start the instance
                    ec2_client.start_instances(InstanceIds=[instance_id])
                      
                    # Wait until instance state changes to running
                    waiter = ec2_client.get_waiter('instance_running')
                    waiter.wait(InstanceIds=[instance_id])
                      
                    print(f"Instance {instance_id} started successfully.")
        else:
            print("No stopped instances found with the specified tag.")
      
    except Exception as e:
        print(f"An error occurred: {e}")
  
    print("Lambda function execution completed.")
  # Uncomment the line below for testing locally
  # lambda_handler(None, None)
  

• Amazon EventBridge Rules: Set up EventBridge rules to schedule triggering of Lambda functions at specific times (e.g., 8:00 am and 6:00 pm) to start and stop EC2 instances.
  • start-ec2-dev-instance:
  • stop-ec2-dev-instance:
• Amazon SNS Topic: Create an SNS topic to which notification alerts will be sent upon successful start and stop actions of EC2 instances. Obtain the ARN (Amazon Resource Name) of this topic for use in your Lambda functions.
  • For this we will reuse the same eventbridge we have created here (section AWS EventBridge 🎉)
• Result: EC2 is shut down after office hours and email notification is sent about the EC2 event shutown

  IAM Role Configuration (Points to remember)

• 🤝 Create an IAM role with permissions of Lambda to Cloudwatch, EC2 and VPC.
• 📜 Attach the IAM role to eventbridge to call the lambda functions.

Resources 📚

• AWS Lambda Documentation
• Amazon EventBridge Documentation
• Amazon SNS Documentation

Acknowledgements 🙏

Special thanks to the amazing communities AWS for their fantastic tools and resources.

Happy coding! 🎉

GITHUB Repository

GITHUB