Sign in Get started

SETUP GUIDES · SELF-HOSTED

Upgrading self-hosted Claspine

What to do when you move your project to a newer Claspine version, release by release.

⏱ A few minutes per note

Most Claspine releases need nothing from you: change the version and build. When a release needs a change in your code or database, it has an upgrade note below. Read every note between your current version and the one you are moving to, oldest first. AI coding agents can read the same notes inside the Claspine package itself (META-INF/spine/upgrades/ in grahmur-platform-foundation), so you can simply ask your agent to upgrade Claspine and follow the notes.

Words you’ll see

Package registry
A server that hands out code libraries to build tools. Maven (Java) and npm (JavaScript) download the libraries your project lists from registries. Claspine Packages is Claspine’s private one, at api.claspine.com/packages.

Before you start

  • A database backup, before moving production to a new version.

Steps

  1. Find your current version: grahmur.platform.version in your pom.xml.
  2. Read the notes below for every newer version up to your target, oldest first, and do each checklist.
  3. Change the version and run ./mvnw verify. Claspine’s build checks point at anything a note asks you to change.
  4. In production, start one instance of the new version first and look for the log lines the note mentions, then start the rest.
Claspine 0.22.0: platform tables and collections are renamed from platform_… to spine_platform_… so they cannot clash with your own tables. Claspine renames them by itself at the first start (PostgreSQL, MongoDB; on Azure Cosmos DB it copies them and keeps the old ones as a backup). Check your own code for direct uses of the old names:
# find code that names Claspine's tables directly (use Claspine's APIs instead)
grep -rnE "\bplatform_(products|deployments|memberships|organizations|sessions|audit_events|payment_orders|domain_bindings|identity_accounts|brands)\b" --include='*.java' --include='*.sql' .

# after a copy on Cosmos DB, once everything works, drop the old platform_* collections

What goes where in Claspine

Console fieldValue
0.22.0Tables and collections renamed to spine_platform_* (automatic). Code that names them must change. Full note: docs/upgrades/0.22.0.md in the Claspine package.
0.23.0New optional setup from settings (platform.bootstrap.*); your app’s own MongoDB repositories keep working; Node SDK sign-in fixed (new response types). Full note: docs/upgrades/0.23.0.md in the Claspine package.
0.23.1Use instead of 0.23.0: your MongoDB is kept only when your code uses it (platform.persistence.application-mongo to override). Full note: docs/upgrades/0.23.1.md.
0.23.2Real providers (storage, email, SMS, push, AI, app stores) start when you switch them on; remove any workaround you added. Full note: docs/upgrades/0.23.2.md.
0.24.0Sign-in with one-time codes by SMS, WhatsApp or email, sent with your own provider account; memberships can wait for approval (PENDING); Twilio SMS fixed. Full note: docs/upgrades/0.24.0.md.
0.25.0Your code can no longer reach Claspine’s own tables: queries are refused at runtime, production will not start with such code, and tests fail on it. Use the APIs (new lookups by key). Full note: docs/upgrades/0.25.0.md.
0.26.0Payments: refund part of an order, cancel an unpaid order (its checkout closes), and a refund the provider did not make now throws and leaves the order paid. Payments that reach a cancelled order are refunded. Healthcare pack: cancel, edit and unlink investigations. Full note: docs/upgrades/0.26.0.md.
0.27.0Healthcare pack: list a clinic's resulted investigations (listResultedByOrg) instead of reading the pack's collection. Full note: docs/upgrades/0.27.0.md.
0.28.0The audit log and other users' notification deliveries need permissions (spine.audit.read, spine.notifications.deliveries.read). Sandbox payments work only in development and test. Stripe refunds and disputes are recorded. Node apps can refund and cancel. Full note: docs/upgrades/0.28.0.md.
0.28.1Use instead of 0.28.0: apps that turn the files, AI and payments HTTP APIs off (platform.engine.data-plane-enabled: false) start again. Full note: docs/upgrades/0.28.1.md.
0.30.0Spine is now Claspine: install @grahmur-org/claspine-client (was spine-client) and @grahmur-org/eslint-plugin-claspine, use the image api.claspine.com/claspine/engine, and point your build at api.claspine.com. Maven coordinates, settings and tables are unchanged. New, optional: direct messages (email and WhatsApp to an address, without an account). Full note: docs/upgrades/0.30.0.md.
0.31.0Engine: mount your message templates at /config/notifications (they could not be loaded before) and give the service key the messages scope. New Claspine Atlas projects start with a test key. Full note: docs/upgrades/0.31.0.md.

Keep it safe

  • Always take a database backup before starting a new version in production.
  • Pin exact versions in your build, so upgrades happen only when you choose.
  • Never query Claspine’s tables from your own code; use the capability APIs. Your build will flag it.

Claspine stores the values encrypted, never shows them again in full, and never sends them to your app or SDK.

If something goes wrong

Startup says tables exist that were not created by Claspine.
Your database already has tables with Claspine’s names. Give Claspine its own database or schema (see the isolation guides) or rename your tables.
Startup on Firestore says the database holds platform data under the pre-0.22 names.
Copy each platform_… collection to spine_platform_… before starting 0.22.0, or contact support.

← All setup guides