Start here
Upgrade Blnk Core
Upgrade a Core instance you operate yourself, from any version to a later one.
This guide shows how to upgrade a Core instance you operate yourself, including production, without surprising your app. This page is about Core version upgrades.
Goal
Upgrading should not surprise your app. If a release changes how something works, follow that release’s migration guide and update your app or config so behaviour stays what you expect, or so you knowingly adopt the new behaviour.
How to go from any version to any later version
- Write down your current Core version and the version you want, preferably the latest version.
- From the migration guide index, open every migration guide for a version after your current version and up to your target. Read them oldest first.
- For each guide, check if it affects you, then do the steps so your app keeps working the way you need.
- Only then deploy the new Core version.
Migration guide index
Use this table to see which guides apply to your upgrade. Open every guide for a version newer than your current Core and not newer than your target.
| Version | What to review |
|---|---|
| 0.10.5 | Bulk transfers may finish in the background instead of before the API responds. Check anything that assumes balances are already updated. |
| 0.11.0 | Search needs a newer Typesense version. Update that service with Core or search can break. |
| 0.12.0 | Existing API keys stop working. Plan to create new keys and update every client that stores them. |
| 0.13.2 | Duplicate transaction references can block the upgrade. Clean them up before you deploy. |
| 0.14.0 | Metadata update responses use a different field name. Fix any code that reads the old name. |
| 0.14.3 | Hook management requires the master key. Scoped keys can only manage API keys for their own owner and cannot escalate scopes. |
| 0.15.0 | Some errors return different HTTP statuses; rate, currency_multiplier, and modification_ref are removed; commit and void may finish in the background; reconciliation start responses include less detail. |
| 0.15.1 | If you set a custom lock duration, confirm it still means what you expect, and clear any stuck balance locks after upgrade. |
| 0.15.4 | Missing balances on transaction routes return BAL_NOT_FOUND; already-refunded returns TXN_ALREADY_REFUNDED; both sources[] and destinations[] is rejected with 400; server.ssl starts HTTPS again. |
When new migration guides ship, they appear here and in the sidebar. The upgrade process stays the same. For features and fixes that are not breaking changes, see the Blnk Core changelog.
Production upgrade checklist
Note what you run today
Record your current Core version, Typesense version if you use search, SDK versions, and the flows you care about (bulk transfers, inflight commit or void, API keys, hooks, metadata, search, custom lock settings).
List the guides you must read
From the migration guide index, take every version newer than your current Core and not newer than your target. Open those guides oldest first.
Example: on 0.12.1 going to 0.15.5, read 0.13.2, then 0.14.0, then 0.15.0, then 0.15.1, then 0.15.4. Skip guides at or below your current version. 0.15.5 has no migration guide.
Update your app where needed
Follow each guide. If a guide shows how to keep old behaviour, use that unless you mean to switch. Prefer setting the behaviour you want in requests or config instead of relying on a changed default.
Try the upgrade on staging first
Use a copy of production data if you can. Run the upgrade, then exercise your critical flows and check that responses and webhooks still match what you expect.
Back up before production
Back up Postgres before you upgrade production. If you rely on work still in the queue, note Redis and queue state as well. See Backup to disk and Backup to S3.
Deploy
Use the same approach as Deploy: move server and worker to the same new version, let startup run database migrations, and keep shared Postgres and Redis config aligned.
For 0.15.3 and later, pull ghcr.io/blnkfinance/blnk:<version>. For 0.15.2 and earlier, keep jerryenebeli/blnk:<version>.
Check after deploy
Confirm the service is healthy, post a few test ledger transactions, confirm queued work is processing, and confirm auth still works. Finish any post-upgrade steps from the guides you followed (for example new API keys after 0.12.0, or stuck lock cleanup after 0.15.1).