DEV Community: Dinesh Wijethunga

5 Laravel Migration Mistakes That Made It Into Production (and How to Repair Them)

Dinesh Wijethunga — Wed, 05 Aug 2026 16:10:11 +0000

TL;DR: A migration I shipped created a column literally named 36. It is still in production. Here are five migration mistakes from a live Laravel e-commerce store, what each one actually did to the schema, and how to repair them without downtime.

Every schema article you have read shows you the clean version — including one of mine. The tables are tidy, the indexes are deliberate, and the author implies they got it right the first time.

Here is the other half. Seven weeks after that schema went live, the cart tables had picked up four follow-up migrations, one silent bug that is still sitting in production today, and a repair migration that quietly contradicts the one before it. None of this is hypothetical: I pulled the column list off the live database while writing this.

Mistake #1: calling char() without a column name

This is the one that still makes me wince. The migration was named add_oId_selected_user_id_to_cart_items_table. The intent was obvious — add a 36-character UUID column called oId. This is what shipped:

Schema::table('cart_items', function (Blueprint $table) {
    $table->foreignId('user_id')->nullable()->constrained();
    $table->char(36)->nullable();          // <-- the bug
    $table->json('selected')->nullable();
});

Why it is wrong

Laravel's signature is char(string $column, ?int $length = null). The first argument is the column name, not the length. Passing 36 makes it the name — PHP happily coerces the integer 36 to the string "36", no error, no warning, migration exits green.

So instead of a 36-character column named oId, the database got a column named 36 at the default length of 255. Here it is on the live server right now:

mysql> SHOW COLUMNS FROM cart_items;

Field                | Type            | Null | Key
---------------------+-----------------+------+-----
row_id               | varchar(255)    | NO   | MUL
oId                  | varchar(255)    | YES  |
...
36                   | char(255)       | YES  |
selected             | json            | YES  |

Note that oId exists too — added six weeks later by a different migration, as a varchar(255). So the table carries both the mistake and its replacement, and the replacement is not even the type that was originally intended.

The migration ran green because there is nothing invalid about a column named 36. MySQL allows it. Every test passed. Nobody noticed for six weeks.

The correct way

Schema::table('cart_items', function (Blueprint $table) {
    $table->char('oId', 36)->nullable()->after('row_id');
});

And to clean up after the fact — note that a numeric column name has to be quoted in raw SQL, though Laravel's builder handles it for you:

Schema::table('cart_items', function (Blueprint $table) {
    if (Schema::hasColumn('cart_items', '36')) {
        $table->dropColumn('36');
    }
});

Check it is empty before you drop it. On this store it is entirely NULL, because nothing ever wrote to a column no code knew existed:

SELECT COUNT(*) AS non_null FROM cart_items WHERE `36` IS NOT NULL;

There is a final twist. When I ran that check while writing this, 36 came back with zero non-null rows — expected, since no code ever referenced it. But so did oId. The replacement column is empty too. Six weeks of migration churn, a bug that reached production, and a repair migration to fix it, all for a feature that was never finished. That is worth sitting with: the cost of a sloppy migration is not only the bad column, it is every migration you write afterwards to work around it.

Mistake #2: promising the schema is final

My original write-up of this schema ended with a confident claim: get the composite indexes and nullable columns right on day one, and you will never need a painful migration during a peak-traffic sale.

The migration log disagrees. Between 12 November and 29 December:

Date	Migration	What it added
Nov 12	`add_order_id_status_to_cart_table`	`order_id`, `status`
Nov 16	`add_oId_selected_user_id_to_cart_items_table`	`user_id`, `36`, `selected`
Dec 29	`add_user_columns_to_cart_items_table`	`selected`, `oId` (both guarded)
Dec 29	`add_user_shipping_method_columns_to_carts_table`	`shop_shipping_method_id`

Why it is wrong

Not because the schema was careless — the four core tables and their composite uniques have never changed. It is wrong because you cannot know your query patterns before the product has users. status only became obviously necessary once someone asked for a report grouping carts by active, converted, abandoned, and expired. Nobody thinks of that on day one.

The correct way

Design for additive change instead of claiming finality. Concretely: add a status column from the start even if it only ever holds one value, because every reporting query eventually wants one and backfilling it later means inferring history you no longer have. Keep new columns nullable so the migration never locks a large table rewriting rows. And treat "we needed another column" as normal, not as failure.

Mistake #3: commenting out a block instead of deleting it

The December repair migration shipped like this:

Schema::table('cart_items', function (Blueprint $table) {
    // User support
//  $table->foreignId('user_id')
//      ->nullable()
//      ->after('cart_id')
//      ->constrained()
//      ->cascadeOnDelete();

    if (!Schema::hasColumn('cart_items', 'selected')) {
        $table->json('selected')->nullable()->after('options');
    }
});

Why it is wrong

A commented-out block carries no information. Six months later nobody can tell whether it means "not yet", "already handled by the November migration", or "this broke production and we backed it out". All three are plausible readings of the same five lines, and they imply completely different next actions.

Git already stores the history. The commented code is not a record, it is ambiguity.

The correct way

Delete it. If the reason matters, say it in one line:

Schema::table('cart_items', function (Blueprint $table) {
    // user_id was already added by the 2025_11_16 migration.
    if (!Schema::hasColumn('cart_items', 'selected')) {
        $table->json('selected')->nullable()->after('options');
    }
});

Mistake #4: hasColumn() guards used to paper over drift

Look at that December migration again. It adds selected — a column the November migration already added — wrapped in a Schema::hasColumn() check. Same story for oId, and for shop_shipping_method_id on the carts table.

Why it is wrong

To be fair to the pattern: these guards are legitimate in real situations — squashed migration histories, per-tenant schemas that genuinely diverge, or a shared package migration that may or may not have run. That is not what happened here.

Here they appear because the author was not sure whether the November migration had fully applied. The guard makes the migration safe to re-run, which is good, but it also makes environment drift invisible, which is the actual problem. A migration that works whether or not the previous one ran is a migration that has stopped telling you the truth about your schema.

The tell is that the guarded oId was added as string (varchar 255) while the November attempt was char. Two different intentions for the same column, six weeks apart, neither aware of the other.

The correct way

Find out what actually ran before writing the repair:

php artisan migrate:status

Then write a migration that states one intention plainly, and reserve hasColumn() for schema that is genuinely conditional rather than merely uncertain.

Mistake #5: repairing with the wrong type

The column that finally landed is oId varchar(255). The name and the original char(36) attempt both say the same thing: this holds a UUID.

Why it is wrong

A UUID string is always exactly 36 characters. Declaring it varchar(255) gives up a fixed-width guarantee for nothing, and if the column is ever indexed the index entry is sized for the declared maximum, not the actual data. On a hot table like cart_items that is real cost for zero benefit.

The correct way

// A UUID is fixed-width. Say so.
$table->char('oId', 36)->nullable();

// Or, if you control the write path and want it compact:
$table->uuid('oId')->nullable();

Changing an existing column's type needs doctrine/dbal on older Laravel versions, and on a large table it is a rewrite — do it in a maintenance window or with an online schema change tool, not casually during a sale.

Conclusion

Four of these five are the same underlying failure: a migration that ran successfully while doing the wrong thing. char(36) exited green. The guarded re-adds exited green. The commented block exited green. Nothing in CI can catch any of them, because nothing about them is invalid — they are merely wrong.

The habits that would have caught them are unglamorous:

Read the generated SQL, not just the migration. php artisan migrate --pretend would have shown add `36` char(255) in about one second.
Diff the live schema against what you think you have. A SHOW COLUMNS in code review is cheaper than a six-week-old mystery column.
Treat a hasColumn() guard as a question, not an answer. If you needed one, find out why first.
Assume you will need more columns. Additive change is normal; pretending otherwise is what makes it painful.

The schema itself held up fine — the four tables and both composite uniques are untouched since launch, and I would design them the same way again. It was the follow-up migrations, the ones nobody reviews as carefully, that did the damage.

If you want the schema those migrations were built on, I wrote it up in full: the complete shopping cart database design, including the two composite unique constraints that turned out to be the only decisions I did not have to revisit.

Cinematic AI Video Prompts: A Step-by-Step Formula

Dinesh Wijethunga — Tue, 04 Aug 2026 20:33:57 +0000

TL;DR: Amateur AI clips come from underspecified prompts. Name the camera move, the lens, the light and the grade, and the model stops guessing. The order that works: subject, setting, action, camera, lens, lighting, mood, film-look, then the technical flags. Keep every prompt free of logos and readable screens — that one rule improves quality and makes the footage reusable.

This is post #3 of the AI Video Automation series. The prompts below are the ones that go in the prompt column of the shot list the batch runner walks.

Why most AI clips look amateur

Almost always the same cause: the prompt names a subject and stops. "A mechanic in a workshop." The model then has to invent the camera position, the movement, the lens, the light and the colour — and it invents all five badly, because there is no signal telling it what to do.

A cinematic prompt removes the guessing by stating what a cinematographer would decide before rolling. That is the entire technique. Everything below is detail on how to say it.

The prompt anatomy

Write the elements in this order. Models weight earlier tokens more heavily, so subject and setting lead, and technical flags trail:

[subject] + [setting] + [action] +

[camera movement] + [lens/framing] +

[lighting] + [mood] + [film-look] +

[technical: aspect ratio, duration, motion intensity, seed]

A complete example that renders cleanly:

A confident mechanic in clean overalls in a workshop, arms crossed,

slight smile, looking just off-camera — slow push-in, 50mm, shallow

depth of field — soft directional window light — calm, assured mood —

cinematic teal-and-amber grade, photorealistic — 9:16, 5s, motion: low

And a real establishing shot from a production b-roll bank, following the same order:

Wide interior of a busy modern auto workshop, two cars raised on

hydraulic lifts, tools neatly arranged, shafts of warm afternoon

sunlight cutting through a large roller door, faint dust in the air,

slow steady dolly-in, 35mm, shallow depth of field, cinematic

teal-and-amber grade, photorealistic, motion: low

Note how much of that prompt is not the subject. "Shafts of warm afternoon sunlight," "faint dust in the air," "slow steady dolly-in" — those clauses are doing the cinematic work.

The load-bearing lines

If you only add four things to a bare prompt, add these:

Camera movement — "slow push-in", "gentle handheld drift", "steady dolly-in". This single line is the biggest quality jump available. A static prompt produces a static, lifeless clip.
Lighting — "warm afternoon light through a window", "soft directional light", "golden hour". Light is what actually reads as cinematic; grade alone does not fake it.
Lens and framing — "35mm, shallow depth of field", "macro close-up". Gives depth and tells the model where to put focus.
Film-look — "cinematic teal-and-amber grade, photorealistic". Anchors both colour and realism, and stops the output drifting toward illustration.

Then one dial: motion intensity. Keep it low for people and subtle shots, medium for action. High motion on a human face warps it — this is the single most reliable way to ruin an otherwise good clip.

Model selection is part of the prompt

Which model you send a shot to matters as much as the wording, and the two decisions are linked.

Kling 3.0 — strongest for realistic people and controlled camera moves. Use it for hero shots. Keep the action to one clear beat; multi-action prompts wobble in a five-second clip.
Seedance 2.0 — faster and cheaper, excellent for abstract motion, gradients and background plates. Reserve it for non-hero shots.
Duration — 5–6 second clips render more reliably and cost fewer credits than long ones. You cut them down in the edit anyway.

That advice is not theoretical. Across a real 57-shot library the split came out as:

Model	Shots	Used for
Kling 3.0	34	Hero shots — people, controlled moves
Seedance 2.0	12	Background plates, abstract motion
Nano Banana Pro	6	Stills where a still will do
Text-to-speech	5	Voiceover

Roughly a 3:1 ratio of hero to background. Sending those 12 background plates to Kling instead would have changed nothing visible and cost noticeably more — the kind of decision that only shows up when you price the library before running it.

The brand-neutral rule

Keep every prompt free of logos, product names and readable screens. This is worth stating as a rule because it wins twice.

It improves quality. Current video models render text as garbled pseudo-lettering. Ask for a screen with a UI and you get something that looks broken. So write the screen out of the shot instead:

Close-up of a technician's hands holding a rugged tablet in a workshop,

tapping and swiping, screen deliberately out of focus / glare so no UI

is readable, grease-flecked fingers, soft window light, macro, shallow

depth of field, cinematic, photorealistic, motion: low

"Screen deliberately out of focus / glare so no UI is readable" is doing real work there. You composite the actual interface in the edit, where it renders perfectly because it is a real screenshot.

It makes the footage reusable. A clip with no branding in it can serve any project. A generated library built this way keeps its value after the campaign it was made for is finished — which changes the economics of generating it at all.

Common mistakes

No camera or lighting direction. The single biggest cause of flat, amateur output.
Readable text or logos. Models render text as garbled shapes. Composite it later.
Too much action in five seconds. One clear beat per short clip; chain beats in the edit.
Generating once. Run 3–5 seeds, keep the best, discard the rest. First takes are rarely the best takes.
High motion on faces. Warping is almost guaranteed. Drop to low.
Requesting on-screen UI. Ask for glare or defocus instead.

Seeds are how you get consistency

A seed makes a generation reproducible — same prompt plus same seed gives you the same clip. Two consequences worth knowing.

First, running 3–5 seeds per hero shot is not waste; it is how you get a choice. The model's output varies enough between seeds that the third attempt is often materially better than the first, and you cannot tell which without generating them.

Second, once you find a seed that works for a subject, reuse it across related shots. That is the closest thing to character consistency these models offer, and it costs nothing extra.

Worth being deliberate about, though: seeds multiply spend. In a batch, video shots get multiple seeds and stills usually get one — a still that is nearly right can be fixed in an image editor, where a video clip cannot.

Putting it together

Apply the anatomy across a whole shot list and the output stops being a lucky dip. Every row carries the same structure, the same grade language and the same motion discipline, so the clips cut together as if they were shot by one person on one day — which is the actual goal.

The next question is what all that generation costs, and it is not what the pricing page suggests.

How to Automate AI Video Creation with Claude & Higgsfield — the pipeline these prompts feed
Higgsfield Credits vs Unlimited: Real Per-Clip Cost Breakdown — what each of those seeds actually costs
Automate Higgsfield with a Python Batch Queue Runner — running the whole list hands-off
Browse the AI Video Automation series

How to Automate AI Video Creation with Claude & Higgsfield

Dinesh Wijethunga — Tue, 04 Aug 2026 20:33:51 +0000

TL;DR: Claude writes and manages the prompts, the Higgsfield CLI generates the clips, and DaVinci Resolve's Python API assembles the edit. Everything is driven by one CSV shot list. The constraint that shapes the whole design: Higgsfield's "unlimited" applies to the web UI only — the CLI bills credits on every generation.

This is the hub post for a series documenting a real AI-video pipeline: one I built to produce cinematic marketing clips at scale, then ran overnight against a metered API. Below is the whole architecture, the file format that holds it together, and the constraints that dictated most of the design decisions.

What the pipeline does

The goal is narrow: turn a list of scene descriptions into a folder of finished clips with as little clicking as possible. Three tools, three jobs.

Tool	Role	Produces
Claude	Writes and manages cinematic prompts, and the automation code around them	A prompt library and the batch runner
Higgsfield CLI	Generates clips via Seedance 2.0, Kling 3.0, Nano Banana Pro	Raw video and image files
DaVinci Resolve	Assembles clips into a finished edit via its Python API	The rendered video

Claude does not generate video. It orchestrates: prompt authoring at volume, and the glue code that turns a list into a run. The rendering happens in Higgsfield's models.

How the pieces connect

Everything flows through one structured file — a CSV shot list. That single source of truth is what makes the pipeline reproducible rather than a sequence of remembered steps:

shot list (CSV)  ->  Higgsfield CLI (generate)  ->  clips/ + manifest

                                                        |

                                                        v

                                        DaVinci Resolve (Python) -> final.mp4

The generator walks the list. The editor reads the manifest of finished clips and lays them onto a timeline. No stage depends on a human remembering what came before, which is the only way an overnight run is possible.

The shot list schema

This is the actual header the batch runner expects. It is worth getting right early, because every later stage reads from it:

id,product,category,model,prompt,aspect,duration,mode,resolution,priority

Two columns do more work than they look like they do:

category — video, image or audio. This is what lets the runner split the list across separate worker queues rather than processing everything in one line.
priority — because a run gets interrupted. Ordering by priority means the shots that matter are already done when it does.

model being per-row is deliberate too. A hero shot and a background plate do not need the same model, and as the cost table below shows, pretending they do is expensive.

The constraint that shaped everything: credits vs unlimited

Higgsfield advertises unlimited generation. That is true — in the web UI. The CLI and API always bill credits. Their own pricing page states it plainly:

Unlimited models and Free Generations are accessible only via higgsfield.ai and are not accessible on MCP/CLI, Canvas or Supercomputer.

I confirmed it the expensive way: one Nano Banana Pro image through the CLI dropped my balance from 10 credits to 8.

This matters more than it first appears. Automation means the CLI. So the moment you build a pipeline, you are on the metered path — and every design instinct you would carry over from an unlimited tier is wrong. You cannot over-generate and pick the best. You generate one strong take per shot and regenerate only failures.

Generation	Credits
Seedance 2.0, 1080p 5s	45
Seedance 2.0, 720p 5s	22.5
Kling 3.0 pro, 5s video	12.5
Kling 3.0 std, 5s video	10
Kling 3.0 std, 3s video	6
Nano Banana Pro image, 2K	2

Note the top two rows: dropping Seedance from 1080p to 720p halves the cost. On a library of forty-odd shots that single decision is the difference between one plan tier and the next. Always price a shot before batching it:

higgsfield generate cost seedance_2_0 --duration 5 --resolution 1080p --prompt "test"



  

  

  45 credits — drop to 720p and it is 22.5

Two constraints that dictated the architecture

Beyond cost, two properties of the CLI shaped how the batch runner had to be written. Both are the kind of thing you only discover by running it.

1. The relaxed queue allows one video and one image at a time

On a trial, concurrency is not "how many workers can I spawn" — it is two slots, one per media type. That maps to exactly two worker threads, each draining its own queue sequentially. More workers do not go faster; they just queue behind each other. This is why the shot list has a category column: it is the key the runner splits on.

2. The CLI does not reliably save to disk

higgsfield generate create ... --wait --json blocks until the generation finishes and returns JSON containing a result URL. The output is URL-based, so the pipeline downloads the file itself rather than trusting the CLI to write it.

That one detail has consequences everywhere: the runner needs its own download step, its own retry logic around that download, and a disk-space guard — because an overnight run that fills the volume at 3am fails in a much worse way than one that stops cleanly.

Why these three tools

Claude — prompt engineering at volume, and writing the glue. Forty cinematic prompts that share a house style is a language problem, not a video problem.
Higgsfield — a multi-model aggregator, so one CLI reaches Seedance 2.0 and Kling 3.0 for video, Nano Banana Pro for stills, and text-to-speech, each selected per row.
DaVinci Resolve — free, professional, and scriptable through a Python API, so assembly automates too instead of being a manual timeline drag at the end.

The aggregator point is the one worth dwelling on. Integrating three video models directly means three APIs, three auth schemes and three billing models. One CLI with a model column in a CSV is a materially smaller system.

What a run actually looks like

Three phases, and the first two exist because the third costs money:

Dry run. Walk the shot list and print every command without generating anything. Catches malformed rows and bad model names for free.
Measure one. Generate a single clip and check the credit delta against the estimate. This is how you find out that a row is 45 credits rather than 22.5 before multiplying it by forty.
Full run. Both slots saturated, retries with backoff, resume from the manifest if it dies.

Resume-from-manifest is not optional at this scale. A run that cannot resume is a run you cannot afford to interrupt, and something always interrupts it.

Sizing the spend

A roughly 46-shot cinematic library, one take each — Kling pro for hero shots, Seedance 720p for backgrounds, cheap stills where a still will do — comes to about 750–1,000 credits.

Which makes plan choice straightforward: a 1,200-credit tier covers one full library pass plus around 35 regenerations, which is the right shape for a single project. A 3,000-credit tier only makes sense if you genuinely want two or three complete takes of everything. And if budget is zero and time is not, do it by hand in the web UI on a trial — unlimited, but slow and entirely manual.

The rule that falls out of all of this: explore free in the web UI, then pay for credits only once you automate.

What the rest of the series covers

This post — the architecture, the shot list, and the credit model.
Cinematic prompt formula — the prompt anatomy that produces usable Seedance and Kling output instead of dreamlike mush.
Credits vs unlimited — the full cost table and when each path makes sense.
Python batch queue runner — generating a whole library hands-off, with retries, resume and the two-slot worker model described above.

Cinematic AI Video Prompts: A Step-by-Step Formula — the prompt anatomy behind every row in the shot list
Higgsfield Credits vs Unlimited: Real Per-Clip Cost Breakdown — the measured costs in full
Automate Higgsfield with a Python Batch Queue Runner — the runner that executes the shot list
Browse the AI Video Automation series

How to Debug GitHub Actions CI Failures Systematically

Dinesh Wijethunga — Mon, 03 Aug 2026 05:00:08 +0000

CI failures have a reputation for being cryptic. After years of staring at GitHub Actions logs, I've found that 90% of all failures fall into one of five categories. If you know the categories, you can diagnose any failure in under 10 minutes.

Step 1: Read the Full Log

GitHub Actions collapses log sections by default. Always expand the failing step and scroll to the first error, not the last. PHP and Laravel produce cascading errors — one root cause produces 50 error lines. The one that matters is always at the top.

The Five Failure Classes

Class 1: Missing File or Directory

Symptom: No such file or directory, Please provide a valid cache path, Class not found

Cause: A file exists on your machine but was never committed to git. Common culprits: storage skeleton directories, empty test directories, generated config files.

Fix: Run git status and git ls-files --others --exclude-standard locally. Commit what's missing. For directories, add a .gitignore placeholder so git tracks the folder.

Class 2: Wrong Connection String

Symptom: SQLSTATE[HY000] [2002] Connection refused, cURL error 7: Failed to connect

Cause: CI is trying to connect to a service (database, Redis, Reverb, Pusher, Mailpit) that isn't running in CI.

Fix: Add the service to your workflow services: block, OR set the connection to a CI-appropriate driver:

echo "BROADCAST_CONNECTION=log" >> .env.testing
echo "QUEUE_CONNECTION=sync" >> .env.testing
echo "MAIL_MAILER=array" >> .env.testing
echo "SCOUT_DRIVER=null" >> .env.testing

Class 3: Missing Environment Variable

Symptom: Undefined array key, a 500 where a config value was expected, Target class [X] does not exist

Cause: Your .env.example is missing a key that the application reads. Works locally because your real .env has it; fails in CI because CI starts from .env.example.

Fix: Add the missing key to .env.example with a safe default value.

Class 4: SQL Dialect Mismatch

Symptom: Tests pass locally (SQLite), fail in CI (MySQL). FUNCTION X does not exist, Ambiguous column 'status'

Cause: Raw SQL written against SQLite syntax.

Fix: Replace with MySQL equivalents:

// Wrong (SQLite)
->selectRaw("first_name || ' ' || last_name as full_name")
->selectRaw("strftime('%Y-%m', created_at) as month")

// Correct (MySQL)
->selectRaw("CONCAT(first_name, ' ', last_name) as full_name")
->selectRaw("DATE_FORMAT(created_at, '%Y-%m') as month")

Class 5: Tooling Version Difference

Symptom: A step that worked last week suddenly fails. Different error messages than your local run.

Cause: A dependency was updated — PHPStan 1.x → 2.x dropped config options; ESLint 9 removed legacy commands; PHP 8.4 changed behaviour of some functions.

Fix: Pin major versions in composer.json/package.json for tools that release breaking changes. Check the changelog when a step breaks with a "deprecated option" or "unknown argument" error.

Reproducing CI Locally

The fastest way to debug CI is to reproduce it locally with the same env vars:

# Create a clean test database
mysql -uroot -p -e "DROP DATABASE IF EXISTS your_app_test; CREATE DATABASE your_app_test;"

# Export the same env vars CI uses
export DB_CONNECTION=mysql DB_HOST=127.0.0.1 DB_PORT=3306
export DB_DATABASE=your_app_test DB_USERNAME=root DB_PASSWORD=secret
export QUEUE_CONNECTION=sync BROADCAST_CONNECTION=log

# Run the exact commands CI runs
composer install --no-interaction --prefer-dist
php artisan migrate --env=testing --force
./vendor/bin/pest

If it fails here, iterate fast. If it passes here but fails in CI, the difference is in one of the five classes above.

Reading Exit Codes

Exit code	Meaning
`0`	Success
`1`	Tests ran, some failed
`2`	Configuration error — Pest: test directory not found; PHPStan: config error
`127`	Command not found — binary not installed or not in PATH
`130`	Process killed — usually OOM, increase `--memory-limit`

Exit code 2 from Pest means it never reached your tests. Check that every directory listed in phpunit.xml exists in git and contains at least one test file.

The Diagnostic Checklist

When CI goes red:

Expand the failing step log and find the first error
Identify which of the five classes it belongs to
Check if it's exit code 2 (config) vs 1 (test failure)
Reproduce locally with the same env vars
Fix, push, watch CI — don't guess and iterate blindly

With this system you go from red CI to root cause in minutes, not hours. That's the whole job — build the pipeline once, trust it forever.

This is the final post in the series. If you followed from Post 1 you now have: a GitHub Actions workflow running on every push, Pest tests against real MySQL, PHPStan and Pint quality gates, secure secrets management, zero-downtime VPS deployment, and the debugging playbook for when things go wrong. That's a production-grade CI/CD pipeline — the same foundation I put on every serious Laravel project.

Originally published at dineshstack.com — read the full version with code samples and updates there.

Next.js Build Output Symbols Explained: , , ƒ and

Dinesh Wijethunga — Sat, 01 Aug 2026 17:10:55 +0000

TL;DR: Next.js 16 prints four symbols in its build output — ○ Static, ● SSG, ƒ Dynamic, and ◐ Partial Prerender. If you are looking for λ, it no longer exists; it was replaced by ƒ in Next.js 14.1.

You run next build, and the route table comes back covered in symbols nobody explained:

Route (app)                              Size     First Load JS
┌ ○ /                                    5.02 kB         112 kB
├ ○ /_not-found                            977 B         103 kB
├ ƒ /en/[slug]                           8.14 kB         128 kB
├ ● /blog                                3.71 kB         109 kB
└ ◐ /dashboard                           12.4 kB         141 kB

○  (Static)             prerendered as static content
●  (SSG)                prerendered as static HTML (uses generateStaticParams)
ƒ  (Dynamic)            server-rendered on demand
◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content

The legend is printed underneath, but it only lists the symbols your build actually used — so if you have no partially prerendered routes, you never see ◐ explained, and the first time one appears it looks like an error. Worse, most articles about this still document λ, which current Next.js does not emit at all.

Below is what each one means, and — more usefully — the exact decision tree Next.js walks to choose one, taken from the source in next/dist/build/utils.js.

The four symbols

Symbol	Label	What Next.js says	What it means for you
`○`	Static	prerendered as static content	Built once at build time. Served from disk or CDN. Fastest possible.
`●`	SSG	prerendered as static HTML (uses `getStaticProps` / `generateStaticParams`)	Also built ahead of time, but from a data-fetching function you wrote.
`ƒ`	Dynamic	server-rendered on demand	Runs on every request. Nothing is cached ahead of time.
`◐`	Partial Prerender	prerendered as static HTML with dynamic server-streamed content	A static shell ships instantly, dynamic holes stream in after.

Why ○ and ● are both "static"

This is the distinction that confuses people, because both are prerendered at build time and both serve instantly.

The difference is where the content came from. ○ is a route with no data-fetching function at all — an about page, a privacy policy, anything Next.js can render purely from your components. ● is a route that ran a data function at build time, so Next.js generated HTML from an external source: your CMS, your database, a filesystem read.

Practically: if ● appears on a route, that route's content is frozen at build time, and changing the underlying data does nothing until you rebuild or revalidate.

The decision tree Next.js actually uses

This is the part no explainer covers. Symbol selection is not a lookup — it is a chain of conditions evaluated in a specific order, and the order is why routes sometimes get a symbol you did not expect. Reduced from the Next.js 16 source:

if (pageInfo?.runtime) {
    symbol = 'ƒ';                        // an explicit runtime always wins
} else if (pageInfo?.isRoutePPREnabled) {
    if (isDynamicAppRoute && !pageInfo.hasPostponed) {
        symbol = 'ƒ';                    // PPR on, but nothing was deferred
    } else if (!pageInfo?.hasPostponed) {
        symbol = '○';                    // PPR on, fully static after all
    } else {
        symbol = '◐';                    // PPR on, and something was postponed
    }
} else if (pageInfo?.isStatic) {
    symbol = '○';
} else if (pageInfo?.isSSG) {
    symbol = '●';
} else {
    symbol = 'ƒ';                        // the fallback
}

Three things fall out of this that are worth knowing.

1. ƒ is the fallback, not a diagnosis

Look at the final else. If Next.js cannot prove a route is static, it gets ƒ. That means ƒ does not tell you why a route is dynamic — only that nothing qualified it as static. A single cookies(), headers(), or searchParams access anywhere in the tree is enough, and the build output will not name the culprit.

2. Setting a runtime short-circuits everything

The very first condition is pageInfo?.runtime. If you have declared a runtime on a route:

export const runtime = 'edge';

…it gets ƒ immediately, before any static analysis runs. A route that would otherwise have been fully static becomes dynamic purely because you named a runtime. If you see an unexpected ƒ on a page with no dynamic APIs, check for a stray runtime export first.

3. PPR routes can show any of three symbols

With Partial Prerendering enabled, a route only earns ◐ if something was actually postponed — that is, if Next.js found dynamic content to defer. Enable PPR on a route with nothing dynamic in it and you get plain ○, because there was no hole to stream. Enable it on a fully dynamic route and you get ƒ. Seeing ○ on a route you configured for PPR is not a misconfiguration; it means PPR had nothing to do.

What happened to λ?

Older Next.js used λ (Server) for server-rendered routes. It was replaced by ƒ in 14.1 — the lambda reference made less sense once routes ran in more places than serverless functions.

I checked the installed Next.js 16.2.4 package directly: λ appears zero times in the build output code. If a tutorial shows it, that tutorial predates 14.1. This matters when debugging, because searching for "next.js lambda symbol build" surfaces guidance for a symbol your build can no longer produce.

Version	Server-rendered symbol
≤ 14.0	`λ` (Server)
14.1+	`ƒ` (Dynamic)

The Revalidate and Expire columns that come and go

You may have noticed the build table sometimes has extra columns and sometimes does not. That is deliberate, not a rendering glitch. Next.js builds the header like this:

[
    listType === 'app' ? 'Route (app)' : 'Route (pages)',
    showRevalidate ? 'Revalidate' : '',
    showExpire    ? 'Expire'     : '',
].filter(Boolean)

showRevalidate and showExpire are set by scanning every page for a cache-control value. If not one route in your build sets a revalidation window, the column is dropped entirely. So adding revalidation to a single route makes a new column appear across the whole table — nothing about your other routes changed.

Also worth knowing if you are following an older tutorial: Next.js used to print an ISR legend entry. In 16 that string does not exist in the build output at all — incremental regeneration is now communicated through these two columns instead of a symbol.

The revalidate: 0 trap

This one is genuinely easy to trip over. If a page uses getStaticProps with revalidate: 0, Next.js does not treat it as static-with-instant-revalidation. It reclassifies it as dynamic outright:

if (hasGSPAndRevalidateZero.has(item)) {
    usedSymbols.add('ƒ');
    // ...route is rendered with ƒ in the table
}

So a page you wrote as SSG, which you would expect to show ●, shows ƒ instead — and every request pays for a server render. If you wanted "always fresh but still cached briefly", use revalidate: 1, not 0. Zero means "never cache", and Next.js is telling you so through the symbol.

Reading your own build output

A healthy content site is mostly ○ and ●, with ƒ reserved for routes that genuinely need per-request data — dashboards, anything behind auth, anything reading cookies.

If a route you expected to be static shows ƒ, work through it in this order:

Check for a runtime export. It short-circuits the whole chain, as above.
Look for dynamic APIs — cookies(), headers(), searchParams, connection(). One call anywhere in the rendered tree is enough, including inside a component three levels down.
Check your fetch calls. A fetch with cache: 'no-store' opts the route out of static rendering.
Check for a parent layout doing any of the above. This is the one that catches people — a layout reading cookies makes every route beneath it dynamic, and the build output blames the child.

To see exactly which API forced it, build with more detail:

next build --debug

Quick reference

You see	Read it as	Act if…
`○`	Free. Served from CDN.	Never — this is the goal.
`●`	Free, but frozen at build time.	Content looks stale — add revalidation.
`ƒ`	Costs a server render per request.	You expected static. Work the list above.
`◐`	Static shell + streamed dynamic holes.	Never — this is usually what you want on a mixed page.

The symbols are not decoration. On a content site, the difference between ○ and ƒ across a few hundred routes is the difference between a CDN bill and a server bill.

Originally published at dineshstack.com — read the full version with code samples and updates there.

Zero-Downtime Deploy to a VPS with GitHub Actions

Dinesh Wijethunga — Fri, 31 Jul 2026 20:18:06 +0000

Managed deployment services like Laravel Forge and Envoyer are excellent and I use them on larger client projects. But you don't need them. Everything they do is SSH commands and symlinks, and you can do those yourself for free.

This is the deployment pattern I use on side projects and small client sites. It costs nothing beyond the VPS ($6/month on Hetzner or DigitalOcean).

The Releases Pattern

Instead of deploying directly to /var/www/app, you deploy to a timestamped folder:

/var/www/app/
├── releases/
│   ├── 20260101120000/    ← previous deployment
│   └── 20260708093045/    ← current deployment
├── shared/
│   ├── .env               ← shared across all releases
│   └── storage/           ← shared uploads and logs
└── current -> releases/20260708093045/   ← symlink

Nginx points at /var/www/app/current. When you deploy:

Clone the new release into releases/$(date +%Y%m%d%H%M%S)/
Link shared/.env and shared/storage/ into the new release
Run composer install, php artisan migrate --force, cache config/routes
Flip the current symlink to the new release (atomic — zero downtime)
Reload PHP-FPM
Delete releases older than the last 5

If anything fails in steps 1–3, the symlink was never flipped. Users see nothing. Rollback is one command: ln -sfn releases/previous current && sudo systemctl reload php8.4-fpm.

Server Setup (One-Time)

# Install PHP 8.4 and extensions
sudo apt-get install -y php8.4-fpm php8.4-cli php8.4-mbstring php8.4-pdo \
  php8.4-mysql php8.4-bcmath php8.4-gd php8.4-zip php8.4-intl

# Create directory structure
sudo mkdir -p /var/www/app/{releases,shared}
sudo chown -R www-data:www-data /var/www/app

# Create the deploy user and add SSH key
sudo adduser deploy --disabled-password
sudo mkdir -p /home/deploy/.ssh
# paste your CI public key into authorized_keys
sudo nano /home/deploy/.ssh/authorized_keys
sudo chmod 700 /home/deploy/.ssh
sudo chmod 600 /home/deploy/.ssh/authorized_keys

The Deploy Script

Create scripts/deploy.sh in your repository:

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

DEPLOY_PATH="/var/www/app"
RELEASE="$DEPLOY_PATH/releases/$(date +%Y%m%d%H%M%S)"
CURRENT="$DEPLOY_PATH/current"
SHARED="$DEPLOY_PATH/shared"
KEEP_RELEASES=5

echo "→ Creating release: $RELEASE"
mkdir -p "$RELEASE"
cp -r /tmp/app-release/. "$RELEASE/"

echo "→ Linking shared resources"
rm -rf "$RELEASE/storage"
ln -sfn "$SHARED/storage" "$RELEASE/storage"
ln -sfn "$SHARED/.env" "$RELEASE/.env"

echo "→ Installing dependencies"
cd "$RELEASE"
composer install --no-dev --optimize-autoloader --no-interaction --quiet

echo "→ Running migrations"
php artisan migrate --force

echo "→ Caching"
php artisan config:cache
php artisan route:cache
php artisan view:cache
php artisan event:cache

echo "→ Flipping symlink"
ln -sfn "$RELEASE" "$CURRENT"

echo "→ Reloading PHP-FPM"
sudo systemctl reload php8.4-fpm

echo "→ Cleaning old releases (keeping $KEEP_RELEASES)"
ls -1dt "$DEPLOY_PATH/releases/"* | tail -n +$((KEEP_RELEASES + 1)) | xargs rm -rf

echo "✓ Deployed: $RELEASE"

The GitHub Actions Deploy Job

  deploy-production:
    name: Deploy to Production
    runs-on: ubuntu-latest
    needs: tests
    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
    environment: production

    steps:
      - uses: actions/checkout@v4

      - name: Upload release to server
        uses: appleboy/scp-action@v0.1.7
        with:
          host: ${{ secrets.VPS_HOST }}
          username: deploy
          key: ${{ secrets.VPS_SSH_KEY }}
          source: "api/."
          target: "/tmp/app-release"

      - name: Run deploy script
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.VPS_HOST }}
          username: deploy
          key: ${{ secrets.VPS_SSH_KEY }}
          script_stop: true
          script: bash /tmp/app-release/scripts/deploy.sh

Branch Protection: Locking the Gate

Once this is working, go to GitHub → Settings → Branches → Add rule for main:

✅ Require status checks to pass before merging
Select: Code Quality and Tests (PHP 8.4, MySQL 8.4)
✅ Require branches to be up to date before merging

Now nothing can reach production without passing your full CI pipeline. This is the complete loop: write code → push → CI validates → deploy. The last post covers what to do when that loop breaks.

Originally published at dineshstack.com — read the full version with code samples and updates there.

Managing Secrets and Env Vars in GitHub Actions

Dinesh Wijethunga — Tue, 28 Jul 2026 02:00:06 +0000

The most common beginner mistake with GitHub Actions secrets isn't accidentally committing them — it's putting them in the wrong place and then wondering why the deployment job can't read them.

Three Layers of Secrets in GitHub Actions

1. Repository Secrets

Available to all workflows in the repository:

GitHub repo → Settings → Secrets and variables → Actions → New repository secret

Use for: CODECOV_TOKEN, API keys used in tests, non-environment-specific values.

2. Environment Secrets

Only available when a job targets a specific environment:

GitHub repo → Settings → Environments → New environment → Add secret

Use for: DB_PASSWORD (different for staging vs production), SSH_PRIVATE_KEY (different server per environment), APP_KEY (must be different per environment).

3. Variables (Not Secrets)

Plaintext, visible in logs. Use for: APP_URL, APP_ENV, non-sensitive configuration.

The .env.example Contract

Your .env.example is a contract. Every key your application reads must appear there. Every CI workflow copies this file and overrides specific values.

Rules for .env.example:

All sensitive values: APP_KEY=, DB_PASSWORD=, STRIPE_KEY= — left empty, filled by CI or developer
All non-sensitive defaults filled in: APP_NAME=MyApp, DB_CONNECTION=mysql
Every key that exists in production must exist here

Wrong pattern — hardcoding secrets in YAML:

      - name: Run tests
        run: ./vendor/bin/pest
        env:
          DB_PASSWORD: supersecretpassword123   # visible in git history forever

Right pattern — using secrets:

      - name: Run tests
        run: ./vendor/bin/pest
        env:
          DB_PASSWORD: ${{ secrets.DB_PASSWORD }}

Passport / OAuth Keys

Laravel Passport generates RSA key pairs (oauth-private.key, oauth-public.key). These are gitignored. In CI, generate them fresh each run:

      - name: Generate Passport keys
        run: php artisan passport:keys --force

Run this step after composer install, before migrations or tests. The --force flag overwrites if they already exist — safe in CI since the runner starts fresh every time.

For production, generate once locally and store the values as base64-encoded environment secrets:

# Run locally, then store the output as GitHub environment secrets
php artisan passport:keys
cat storage/oauth-private.key | base64
cat storage/oauth-public.key | base64

In your deploy script, decode them back:

echo "$PASSPORT_PRIVATE_KEY" | base64 -d > storage/oauth-private.key
echo "$PASSPORT_PUBLIC_KEY" | base64 -d > storage/oauth-public.key

Using Environment Secrets in Deploy Jobs

  deploy-production:
    name: Deploy to Production
    runs-on: ubuntu-latest
    needs: tests
    if: github.ref == 'refs/heads/main'
    environment: production   # unlocks the 'production' environment secrets

    steps:
      - uses: actions/checkout@v4

      - name: Deploy via SSH
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.VPS_HOST }}
          username: deploy
          key: ${{ secrets.VPS_SSH_KEY }}

The environment: production line is what unlocks the secrets you added under the production environment in GitHub settings. If you omit it, the job can only access repository-level secrets.

What to Never Put in YAML

Real passwords — use ${{ secrets.X }}
Production API keys — use ${{ secrets.X }}
Private keys — base64-encode, store as secret
Production APP_KEY — environment secret per environment

The test DB password (secret) is fine in plain YAML because the MySQL container only lives for the duration of the CI job and is not accessible from outside the runner network.

In the next post we wire up the final piece: a deploy job that SSHs into your VPS and ships the new release with zero downtime.

Originally published at dineshstack.com — read the full version with code samples and updates there.

Code Quality Gates: Laravel Pint and PHPStan in CI

Dinesh Wijethunga — Sat, 25 Jul 2026 00:00:11 +0000

The moment you add a code quality gate to CI, something quietly changes on your team. Developers stop arguing about code style in reviews because the robot handles it. Static-analysis errors stop reaching production because they can't pass the gate. You stop inheriting other people's technical debt because new errors are blocked immediately, even if old ones exist.

That last point is the PHPStan baseline trick. We'll get to it.

The Code Quality Job

This job runs on every push and is intentionally fast — no database, no migrations, just PHP and a vendor folder:

  quality:
    name: Code Quality
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup PHP 8.4
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.4'
          extensions: mbstring, pdo, bcmath, zip, intl
          coverage: none
          tools: composer:v2

      - name: Cache Composer dependencies
        uses: actions/cache@v4
        with:
          path: api/vendor
          key: php-8.4-composer-${{ hashFiles('api/composer.lock') }}
          restore-keys: php-8.4-composer-

      - name: Install dependencies
        run: composer install --no-interaction --prefer-dist --no-progress

      - name: Check formatting (Laravel Pint)
        run: ./vendor/bin/pint --test

      - name: Static analysis (PHPStan)
        run: ./vendor/bin/phpstan analyse --memory-limit=2G --no-progress

pint --test runs in read-only mode — it checks without modifying files. Exit code 1 if any file has style drift. Run ./vendor/bin/pint locally (without --test) to auto-fix before pushing.

Configuring PHPStan

Add a phpstan.neon to your API root:

parameters:
    level: 8
    paths:
        - app
        - Modules
    excludePaths:
        - vendor
    ignoreErrors:
        - identifier: missingType.iterableValue
        - identifier: missingType.generics

Level 8 is strict. On a fresh project, aim for it from day one. On an existing codebase, start at level 4 and raise it gradually.

The Memory Problem

PHPStan at level 8 on a large codebase needs more than 512MB of RAM. Use --memory-limit=2G in CI. Locally, add a shortcut to composer.json:

"scripts": {
    "analyse": "php -d memory_limit=2G vendor/bin/phpstan analyse --no-progress"
}

The Baseline Trick for Legacy Codebases

Here's the situation I encounter on almost every inherited project: PHPStan level 8 reports 2,600 existing errors. You can't fix them all in one PR. But you also can't ignore level 8 — you need it to catch new errors.

The solution is a baseline file. You generate it once. It records all current errors as "accepted." From that point, any new error fails CI, but existing ones are silenced:

# Run once locally, commit the result
php -d memory_limit=2G vendor/bin/phpstan analyse --generate-baseline phpstan-baseline.neon

Then include it in phpstan.neon:

includes:
    - phpstan-baseline.neon

parameters:
    level: 8
    paths:
        - app
        - Modules

Commit phpstan-baseline.neon. From now on: CI passes on existing debt, fails on new debt. As you fix old errors, re-generate the baseline with fewer entries. Eventually you won't need it.

Ordering Jobs: Quality Before Tests

Use needs: to enforce ordering:

  tests:
    name: Tests (PHP 8.4, MySQL 8.4)
    needs: quality   # this line
    runs-on: ubuntu-latest

Now the test job only starts if quality passed. This saves CI minutes — there's no point running a 3-minute test suite against code that won't pass style checks.

Developer Workflow With These Gates

The new routine before any push:

# Fix style issues automatically
./vendor/bin/pint

# Check for type errors
php -d memory_limit=2G vendor/bin/phpstan analyse --no-progress

# Run tests locally
php artisan test

# Now push — CI will agree
git push origin feature/my-feature

After a few weeks this becomes muscle memory. The quality gate stops being something that catches you and starts being something you pre-empt.

In the next post we cover secrets and environment variables — the right way to handle API keys, database passwords, and OAuth keys in CI without ever putting sensitive values in your YAML files.

Originally published at dineshstack.com — read the full version with code samples and updates there.

How to Contribute to an Open-Source AI Trading Bot

Dinesh Wijethunga — Fri, 24 Jul 2026 23:30:04 +0000

How to Contribute to an Open-Source AI Trading Bot

If you want to contribute to an open-source AI trading bot — and build on a real, running system instead of a toy — this guide shows you exactly how. The Claude-powered crypto bot from Part 1 is MIT-licensed on GitHub, and the most interesting problems in it are wide open. You don’t need to be a quant or an ML expert; there’s meaningful work here for developers, traders, writers, and testers alike.

👋 New to open source? That’s fine — this is a friendly, low-pressure project. A thoughtful question or a docs fix is a real contribution.

Why Contribute to This Project?

Most “AI trading bot” repos are either abandoned demos or paywalled black boxes. This one is different: it’s a complete, documented, honestly-evaluated system where the central question — does it actually have a tradeable edge? — is genuinely unsolved. Contributing here means working on real LLM-agent orchestration, machine-learning signal modelling, exchange execution, and a production dashboard, with a maintainer who’ll actually review your PR. It’s a great portfolio piece and a great way to learn.

Where Help Is Most Needed

Pick whatever matches your skills:

Area	Example contributions
🧠 Strategy & research	New signals, better entry/exit logic, ideas to capture trend (the current strategy is defensive and lags in bull markets)
📈 ML modelling	Feature engineering, calibration, honest walk-forward evaluation, reducing overfitting
🛡️ Risk & execution	Smarter sizing, OCO/bracket orders, slippage modelling, live-trading safety
💻 Dashboard (Next.js)	New visualizations, UX, mobile polish, accessibility
🔧 DevOps	A one-command `docker compose` setup — the single highest-impact task right now
📖 Docs & testing	Setup guides, tutorials, backtest rigor, unit tests, translations

Setting Up the Project Locally

You don’t need a VPS to contribute — run it locally on testnet:

git clone https://github.com/dineshstack/crypto_bot.git

cd crypto_bot

python3 -m venv venv && source venv/bin/activate

pip install -r requirements.txt

cp .env.example .env     # add your own keys; keep TESTNET=true

For the dashboard:

cd dashboard

npm install

cp .env.local.example .env.local

npm run dev

How to Submit Your First Pull Request

The flow is standard GitHub — small, focused changes are the easiest to merge:

git checkout -b feature/your-improvement


  
  
  make your change


python3 -m py_compile changed_file.py     # sanity-check Python

git commit -m "Clear description of what changed and why"

git push origin feature/your-improvement



  

  

  then open a Pull Request against main

In your PR, describe what you changed, why, and how you tested it. Anything touching order execution, sizing, or the circuit breakers gets extra review — describe your testing in detail, and never weaken a safety check without explaining why. The full checklist is in the repo’s CONTRIBUTING.md.

Not a Coder? You Can Still Help

Some of the most valuable contributions aren’t code:

🐛 Report bugs or unexpected behaviour with clear steps to reproduce.
💡 Suggest strategy ideas or share how it behaved in a market regime you tested.
📝 Improve the docs — even a typo fix or a clearer sentence helps the next person.
⭐ Star and share the repo — reach is what brings in more contributors.

Look for issues labelled good first issue to get started.

Let’s Build Something Honest Together

This project is deliberately transparent about what it can and can’t do, which makes it a rare thing in the “AI trading” space: a place to genuinely learn and experiment without hype. If that appeals to you, jump in.

🚀 Ready to contribute?
⭐ Star & fork the repo
💬 Open an issue describing what you’d like to work on
☕ Not contributing code but want to support the work? Buy me a coffee on Ko-fi — it keeps the demo and API running.

The repo is open, MIT-licensed, and waiting for your first pull request.

Tags: Open Source, AI Trading Bot, Contributing, GitHub, Developer Community

Disclaimer: For educational and research purposes only. Not financial advice. Cryptocurrency trading carries substantial risk of loss.

How to Deploy an AI Crypto Trading Bot on Your VPS

Dinesh Wijethunga — Fri, 24 Jul 2026 19:45:04 +0000

How to Deploy an AI Crypto Trading Bot on Your VPS

In this tutorial you’ll deploy an AI crypto trading bot to your own VPS — the open-source Claude-powered bot from Part 1 — and have it analysing BTC and ETH on Binance testnet, messaging you on Telegram, in about 20–30 minutes. I’ll give you the exact steps, a complete list of the API keys you need, an honest running-cost breakdown, and every gotcha I hit so you don’t lose an evening to them.

⚠️ Start on testnet. Everything below uses Binance testnet (fake money). Never point live keys at a bot you haven’t watched run for weeks. This is educational content, not financial advice.

Prerequisites

Before you deploy the AI crypto trading bot, get these ready:

A VPS running Ubuntu 22.04 or 24.04. To run the bot, 2 vCPU / 4 GB RAM is plenty. To train the ML model, more RAM helps — or train it on your laptop and copy the model file over (more below).
Python 3.12 and MySQL 8 on the server.
Accounts and API keys (the next section is a full table).
Basic comfort with SSH and the command line.

The API keys you’ll need

This trips people up, so here’s everything in one place:

Key	Where to get it	Notes
Anthropic API key	console.anthropic.com	Enable billing — the free tier won’t sustain continuous calls.
Binance API key + secret	Binance testnet: testnet.binance.vision	For live later: spot-only, no withdrawal, IP-restricted.
Telegram bot token	@botfather	Create a bot, copy the token.
Telegram chat ID	@userinfobot	Your personal chat ID — the bot only talks to you.
CoinGecko API key	coingecko.com/api	Free tier is fine.

Step 1: Set Up the Server

SSH into your VPS and install the essentials:

sudo apt update && sudo apt install -y python3.12 python3.12-venv python3-pip mysql-server libomp-dev Create the database

sudo mysql -e "CREATE DATABASE crypto_bot;" sudo mysql -e "CREATE USER 'crypto_bot'@'localhost' IDENTIFIED BY 'your-strong-password';" sudo mysql -e "GRANT ALL ON crypto_bot.* TO 'crypto_bot'@'localhost';"

Step 2: Clone and Install the Bot

Clone the repo and run the install script, which sets up the Python virtual environment, installs dependencies, and registers a systemd service that auto-restarts on crash:

git clone https://github.com/dineshstack/crypto_bot.git


cd crypto_bot


bash deploy/install.sh

Step 3: Configure Your API Keys

Copy the example environment file and fill in the keys from the table above. Never commit this file — it’s git-ignored for a reason.

cp .env.example .env


nano .env

ANTHROPIC_API_KEY=sk-ant-...


BINANCE_API_KEY=your_testnet_key


BINANCE_SECRET=your_testnet_secret


TELEGRAM_BOT_TOKEN=your_bot_token


TELEGRAM_CHAT_ID=your_chat_id


MYSQL_PASSWORD=your-strong-password


TESTNET=true          # keep this true

Step 4: Train the ML Model

The bot ships without a trained model — you train it once on historical data. This is the only CPU/RAM-heavy step:

source venv/bin/activate


python3 -c "import ml_signal, market_data as md; ml_signal.train_model(md.get_exchange())"

💡 Low-RAM VPS? Run this same command on your laptop, then copy the generated ml_models/ folder to the server with scp. The bot’s runtime is light; only training is hungry.

Step 5: Start the Bot and Connect Telegram

sudo systemctl start crypto-bot


sudo systemctl enable crypto-bot   # auto-start on reboot

Now open Telegram, find your bot, and send /start. Within a few minutes you’ll get your first analysis message. Useful commands: /status, /analyze, /performance, /history.

Adding the Dashboard (Optional)

The bot is fully functional headless, but the Next.js dashboard is where you see why it does everything. It’s a separate app (plus a Laravel API for auth and role-based access) served behind nginx. The full stack is: bot → Laravel API (php-fpm) → Next.js dashboard (PM2) → nginx reverse proxy with SSL. It’s more involved than the bot itself, so I’m keeping the deep detail in the repo’s deployment docs rather than bloating this post.

🛠️ Wanted: a one-command docker compose up for the whole stack is on the roadmap. If you’d enjoy building it, it’s the single highest-impact contribution right now — open an issue and let’s talk.

What It Costs to Run

Nobody tells you this, and it’s the reason people abandon self-hosted bots. Realistic monthly cost:

VPS: ~$5–$12/month for a 2 vCPU / 4 GB box.
Anthropic API: the 4-hour loop uses cheap Claude Haiku, so the base cost is low; the weekly deep reviews and any research/report generation use pricier models. Budget a small, predictable amount and watch it for the first week.
Everything else (Binance testnet, CoinGecko free tier, Telegram): free.

The takeaway: cheap to run in testnet, but the Anthropic bill scales with how often you trigger the heavy AI features — so keep an eye on it.

Common Mistakes (Gotchas I Hit)

The update script doesn’t pull. deploy/update.sh reinstalls and restarts but doesn’t git pull — run git pull yourself first.
Laravel defaults to SQLite. If you add the dashboard, its API must use DB_CONNECTION=mysql pointed at the bot’s database, or the dashboard shows no data.
Run the migrations and seeder. The dashboard’s roles and admin user come from php artisan migrate + db:seed — skip it and login breaks.
Exchange minimums. Binance rejects orders under a $5 minimum notional — the bot handles this now, but it’s the classic “why did my trade fail at $0” trap.
The weekly review is quiet at first. It stays dormant until there are 7 days of trades to review. That’s expected, not a bug.

You’re Live — Now What?

You’ve deployed an AI crypto trading bot that analyses the market every four hours, explains its reasoning, and asks before it trades. Let it run on testnet for a couple of weeks and watch the /performance numbers accumulate before you even think about real money.

🎉 Got it running? I’d love to see it — drop a comment or a screenshot. And if this guide saved you time:
⭐ Star the repo on GitHub
☕ Support the project on Ko-fi (it covers the API and server costs that keep it running)

First contact: the deployed bot’s analysis message arriving in Telegram.

Part 1 — How I Built an AI Crypto Trading Bot with Claude AI
Part 3 — How to Contribute to the Project

Tags: AI Crypto Trading Bot, VPS Deployment, Self-Hosting, Binance, DevOps

Disclaimer: For educational and research purposes only. Not financial advice, not a solicitation to trade. Cryptocurrency trading carries substantial risk of loss. Always start on testnet and never trade money you can’t afford to lose.

How I Built an AI Crypto Trading Bot with Claude AI

Dinesh Wijethunga — Fri, 24 Jul 2026 18:28:08 +0000

How I Built an AI Crypto Trading Bot with Claude AI

This is the definitive guide to how an AI crypto trading bot built on Claude (Anthropic) actually works — the architecture, the design decisions, and the honest results — so you don’t have to piece it together from a dozen scattered tabs. It’s a real, running system: a multi-agent Claude pipeline for decisions, a machine-learning ensemble for a second opinion, layered risk controls, and a full Next.js dashboard. It trades BTC and ETH on Binance, is controlled from Telegram, and is open source on GitHub.

Part 1 of a 3-part series. This post covers the architecture. Part 2 is a full deploy-to-your-VPS walkthrough, and Part 3 is about contributing. If it’s useful, a ⭐ on the repo genuinely helps.

One honest note up front: this is a research and educational project, currently running in paper-trading (Binance testnet). It is not a get-rich-quick bot and nothing here is financial advice. I’ll show you exactly what my backtests reveal later in the post — the engineering is solid, but “does it print money” is still an open question.

What Is an AI Crypto Trading Bot?

An AI crypto trading bot is software that analyses the market and places trades automatically, using artificial intelligence to make the decisions a human trader normally would. The interesting question isn’t “can it place orders” — that’s trivial — it’s “can a large language model reason through a live, messy, adversarial market and act sensibly.” Crypto is about as messy and adversarial as markets get, which is exactly why it’s a good test.

Rather than one giant “should I buy?” prompt, this bot orchestrates several specialised components: three Claude agents, a quant ML model, and a strict risk-management layer that has the final say before any money moves. Here’s how they fit together.

How the AI Trading Bot Works: The 4-Hour Cycle

The simplest way to understand the system is to follow one cycle. Every four hours — and immediately if a flash crash is detected — the bot runs this loop:

Market data ─┐

News/social ─┼─▶  3 Claude agents  ─┐

On-chain ────┤   (Market · Sentiment · Decision)

Derivatives ─┘                       ├─▶ Decision ─▶ Risk sizing ─▶ Binance

Historical ──────▶ ML ensemble ──────┘        │

                                              └─▶ MySQL ─▶ Dashboard + Telegram

In words, each cycle:

Gathers the market state — 20+ technical indicators, derivatives data (funding rate, open interest, long/short ratio), the Fear & Greed index, and multi-timeframe trend agreement.
Grades its last decision against what the market actually did, and turns mistakes into one-line lessons.
Checks a set of safety circuit breakers that can pause trading or shrink positions.
Asks three specialised Claude agents what to do.
Gets a second opinion from an ML model trained on thousands of historical candles.
Sizes the trade with risk-managed position sizing and executes on Binance with a protective stop-loss (after Telegram approval, in live mode).
Logs everything — every prompt, response, and number — to a database that feeds the dashboard and a Telegram message.

The Multi-Agent Claude Pipeline

The obvious way to use an LLM for trading is one mega-prompt: “here’s everything, tell me buy/sell/hold.” It works, but the reasoning gets shallow — the model tries to hold every consideration at once. So the bot runs three specialised Claude agents instead:

Market Analyst — sees only the chart and the numbers: RSI, MACD, Bollinger Bands, ATR, VWAP, Ichimoku, funding rate, open interest, multi-timeframe regime. A pure technical read.
Sentiment Analyst — sees only the context: news, social sentiment, on-chain flows, options positioning (put/call, max pain), whale transactions, and macro (DXY, S&P, gold, VIX). It runs in parallel with the Market Analyst.
Decision Maker — sees both assessments, plus the ML prediction, the portfolio, and lessons from past mistakes. It has hard rules baked in (won’t over-allocate, won’t panic-sell an uptrend, defaults to HOLD when signals conflict) and produces the final decision as structured JSON:

{

  "action": "buy",

  "confidence": 0.72,

  "trade_usd": 6.0,

  "risk": "medium",

  "reason": "RSI deeply oversold + OBV rising divergence + bullish options

             positioning create an asymmetric reversal setup; macro is a

             headwind but allocation is low, so a small buy is justified.",

  "signals": ["rsi_oversold", "obv_divergence", "options_bullish"]

}

Splitting the problem this way produces better, more legible decisions — each agent focuses, and the final synthesis weighs two clean expert opinions instead of one blurry one. Every call is logged in full, so the dashboard can show the entire chain of reasoning behind any trade. For the fast 4-hour loop I use Claude Haiku; for heavier reasoning (weekly reviews, deep research, reports) I use Claude Fable 5 with an automatic fallback to Claude Opus 4.8.

The Machine Learning Ensemble: A Quant Second Opinion

The Claude agents make the call, but they don’t get the last word alone. Running alongside them is a classic quant model:

A stacking ensemble — XGBoost and LightGBM base learners feeding a logistic-regression meta-learner.
Trained on 5,000+ candles across three timeframes (1h, 4h, 1d), with 60+ engineered features.
Labelled with the triple-barrier method (target / stop / timeout) from Advances in Financial Machine Learning.
Validated with purged walk-forward cross-validation — the honest way to test a time-series model, which stops the future leaking into the past.

A Hidden Markov Model also classifies the market into regimes (strong trend, weak trend, range, high volatility, crash) so the strategy can adapt. The Decision agent treats the ML prediction as one more expert at the table — sometimes it agrees, sometimes it overrides. Keeping them separate means neither a hallucinating LLM nor an overfit model can unilaterally move money.

Risk Management Is the Real Product

Here’s something I believe strongly: a 55%-accurate model with good risk management beats a 65%-accurate model with bad sizing. So most of the engineering went here, not into the “AI” headline. The bot uses quarter-Kelly position sizing, ATR-based stops that widen in losing streaks, protective stop-loss orders resting on the exchange, human approval for every live trade via Telegram, and five circuit breakers:

# Circuit-breaker thresholds (config.py)

DAILY_LOSS_HALT_PCT   = 0.03   # 3% intraday loss -> pause for the day

DRAWDOWN_REDUCE_PCT   = 0.10   # 10% drawdown     -> halve position sizes

DRAWDOWN_HALT_PCT     = 0.20   # 20% drawdown     -> halt all trading

CONSECUTIVE_LOSS_HALT = 5      # 5 losses in a row -> pause



  

  


an equity moving-average filter that throttles sizing in a downtrend

The philosophy: it should be very hard for the bot to lose a lot quickly, even when the AI is wrong — because sometimes it will be.

Common Mistakes When Building an AI Trading Bot

Things I got wrong so you don’t have to:

Trusting the LLM’s suggested trade size. The model would suggest a dollar amount that the risk layer then overrode — and for a while the two disagreed silently. Let one component own sizing.
Ignoring exchange minimums. Binance rejects orders below a $5 minimum notional. Risk-managed sizing quietly produced sub-$5 orders that failed at $0 — roughly half the buy signals were lost before I caught it.
Measuring “correct/wrong” on too short a window. A ±2% move in 4 hours almost never happens in a range-bound market, so every trade scored “neutral” and the win rate was undefined. Measure decisions by real profit-and-loss over a sensible horizon instead.
Backtesting without a leakage check. A backtest that looks amazing is usually cheating. Always run a placebo test (below).

The Tech Stack

Layer	Technology
AI	Claude Haiku 4.5 (fast analysis), Claude Fable 5 + Opus 4.8 (deep reasoning)
Machine learning	XGBoost + LightGBM stacking ensemble, Optuna tuning, HMM regime detection
Trading	Binance Spot API via CCXT, WebSocket for real-time data
Backend	Python 3.12 (bot), Laravel + FastAPI (APIs), MySQL 8
Frontend	Next.js 16, React 19, Tailwind CSS
Control & infra	Telegram Bot API, Ubuntu VPS, systemd, nginx, PM2

Honest Results: What the Backtests Actually Show

This is the section most “I built a trading bot” posts leave out, and it’s the most important. I tested the strategy over 24 months with fees and slippage modelled, plus a placebo/leakage test — feed the model a fake, time-shifted signal; if it still “works,” your harness is cheating. The findings:

No leakage. Under the placebo, the edge collapses — so the good results come from real signal, not a look-ahead bug. This is the check most backtests fail silently.
It survives out-of-sample. On data the model never trained on, across multiple market windows, it stayed positive.
But it’s a defensive, market-neutral scalper. It sidesteps crashes well (up while BTC fell 27%) but underperforms simple buy-and-hold in a bull market, and its absolute returns are small.

In plain terms: it’s a well-engineered platform that protects capital and trades with discipline — but whether it has meaningful, tradeable alpha is still an open research question. I’d rather tell you that than show a cherry-picked equity curve. It’s also exactly where contributions are most valuable.

Conclusion: Get the Code and Build With Me

An AI crypto trading bot is a genuinely fun way to combine LLM reasoning, machine learning, and real-world execution into one system — and building it in the open means the interesting problems (chiefly, “is there real alpha here?”) are shared. The entire project is MIT-licensed on GitHub:

👉 github.com/dineshstack/crypto_bot — ⭐ star it if this was useful.

Want to deploy your own? That’s Part 2: Deploy an AI Crypto Trading Bot to Your VPS — with a real cost breakdown and every gotcha.
Want to contribute? See Part 3: How to Contribute and the repo’s CONTRIBUTING.md.

The dashboard: click any trade to see the full three-agent reasoning, ML prediction, and stop-loss levels.

Part 2 — Deploy an AI Crypto Trading Bot to Your Own VPS
Part 3 — How to Contribute to the Project

Tags: AI Crypto Trading Bot, Claude AI, Machine Learning, Algorithmic Trading, Open Source

Disclaimer: This project is for educational and research purposes only. It is not financial advice and not a solicitation to trade. Cryptocurrency trading carries substantial risk of loss. Never trade with money you can’t afford to lose, and always start on testnet.

Originally published at dineshstack.com — read the full version with code samples and updates there.

Higgsfield Credits vs Unlimited: When to Use Which?

Dinesh Wijethunga — Wed, 22 Jul 2026 19:57:49 +0000

Both Higgsfield's credit plans and its unlimited mode let you generate — but they are not interchangeable, and confusing them will either waste money or break your automation. Here's how to pick, with the real per-clip costs I measured.

This is post #4 of the AI Video Automation series. It's the lesson that cost me the most time, so I put it in its own post.

Overview: two different systems

Higgsfield markets "unlimited generations on all top models." That is true — in the web UI. It is not true for the CLI. Their own pricing page states it directly:

Unlimited models and Free Generations are accessible only via higgsfield.ai and are not accessible on MCP/CLI, Canvas or Supercomputer.

I confirmed it empirically: one Nano Banana Pro image via the CLI dropped my balance from 10 credits to 8. The web UI's unlimited "relaxed" queue and the CLI's credit-metered queue are two separate systems.

Key differences

	Web UI (unlimited)	CLI / API (credits)
Cost	Free on an unlimited plan/trial	Credits per generation
Automation	Manual, one at a time	Fully scriptable
Speed	Relaxed (slow) queue	Priority queue
Best for	Free manual exploration	Hands-off batch pipelines

The real CLI costs (measured)

Generation	Credits
Kling 3.0 pro, 5s video	12.5
Kling 3.0 std, 5s video	10
Kling 3.0 std, 3s video	6
Seedance 2.0, 1080p 5s	45
Seedance 2.0, 720p 5s	22.5
Nano Banana Pro image, 2K	2

Always check before a batch:

higgsfield generate cost seedance_2_0 --duration 5 --resolution 1080p --prompt "test" 45 credits — drop to 720p and it's 22.5

When to use the web UI (unlimited)

You're exploring, testing quality, or making a handful of clips.
You have an unlimited plan or an active trial and don't mind clicking each generation.
Budget is zero and you have time to babysit the relaxed queue.

When to use the CLI (credits)

You're running a batch pipeline — a whole library, hands-off (see post #5).
You want reproducibility, retries, and overnight runs.
You value time over the credit cost.

Verdict / plan sizing

A ~46-shot cinematic library costs about 750–1,000 credits for one take each (Kling pro for heroes, Seedance 720p for backgrounds, cheap images). So:

PLUS (1,200 credits) covers one full library pass plus ~35 regenerations — the right buy for a single project. Bill it monthly and cancel if it's one-off.
ULTRA (3,000 credits) only if you want 2–3 full takes of everything.
Free route: do it manually in the web UI on a trial — unlimited but slow and hands-on.

Rule of thumb: explore free in the web UI, then pay for credits only when you automate.

Output / preview

Now that the cost model is clear, the next post automates the whole thing within a credit budget.

[Insert preview: the cost comparison table — filename higgsfield-credits-vs-unlimited.png]

Previous: Cinematic AI Video Prompts: A Step-by-Step Formula
Next: Automate Higgsfield with a Python Batch Queue Runner
Series hub: AI Video Automation overview

Originally published at dineshstack.com — read the full version with code samples and updates there.

DEV Community: Dinesh Wijethunga

5 Laravel Migration Mistakes That Made It Into Production (and How to Repair Them)

Mistake #1: calling char() without a column name

Why it is wrong

The correct way

Mistake #2: promising the schema is final

Why it is wrong

The correct way

Mistake #3: commenting out a block instead of deleting it

Why it is wrong

The correct way

Mistake #4: hasColumn() guards used to paper over drift

Why it is wrong

The correct way

Mistake #5: repairing with the wrong type

Why it is wrong

The correct way

Conclusion

Cinematic AI Video Prompts: A Step-by-Step Formula

Why most AI clips look amateur

The prompt anatomy

The load-bearing lines

Model selection is part of the prompt

The brand-neutral rule

Common mistakes

Seeds are how you get consistency

Putting it together

Related posts

How to Automate AI Video Creation with Claude & Higgsfield

What the pipeline does

How the pieces connect

The shot list schema

The constraint that shaped everything: credits vs unlimited

45 credits — drop to 720p and it is 22.5

Two constraints that dictated the architecture

1. The relaxed queue allows one video and one image at a time

2. The CLI does not reliably save to disk

Why these three tools

What a run actually looks like

Sizing the spend

What the rest of the series covers

Related posts

How to Debug GitHub Actions CI Failures Systematically

Step 1: Read the Full Log

The Five Failure Classes

Class 1: Missing File or Directory

Class 2: Wrong Connection String

Class 3: Missing Environment Variable

Class 4: SQL Dialect Mismatch

Class 5: Tooling Version Difference

Reproducing CI Locally

Reading Exit Codes

The Diagnostic Checklist

Next.js Build Output Symbols Explained: , , ƒ and

The four symbols

Why ○ and ● are both "static"

The decision tree Next.js actually uses

1. ƒ is the fallback, not a diagnosis

2. Setting a runtime short-circuits everything

3. PPR routes can show any of three symbols

What happened to λ?

The Revalidate and Expire columns that come and go

The revalidate: 0 trap

Reading your own build output

Quick reference

Zero-Downtime Deploy to a VPS with GitHub Actions

The Releases Pattern

Server Setup (One-Time)

The Deploy Script

The GitHub Actions Deploy Job

Branch Protection: Locking the Gate

Managing Secrets and Env Vars in GitHub Actions

Three Layers of Secrets in GitHub Actions

1. Repository Secrets

2. Environment Secrets

3. Variables (Not Secrets)

The .env.example Contract

Passport / OAuth Keys

Using Environment Secrets in Deploy Jobs

What to Never Put in YAML

`45 credits — drop to 720p and it is 22.5`

`then open a Pull Request against main`

`an equity moving-average filter that throttles sizing in a downtrend`