Skip to main content

Migration Guide: Shorebird Cloud to Sovereign TkushPatch

For organizations governed by strict data sovereignty mandates, central bank compliance rules (international banking compliance, sovereignty, and GDPR), or on-premise operational constraints, migrating from the public Shorebird Cloud SaaS to TkushPatch requires zero modification of application business logic.

This guide provides the complete end-to-end migration procedure.

1. Feature Comparison: Shorebird Cloud vs. Sovereign TkushPatch​

Architectural DimensionShorebird Cloud (SaaS)Sovereign TkushPatch
Server HostingThird-party public cloud (US / GCP)Your private servers, bare-metal VPS, or private VPC
Private Signing KeysManaged and held by ShorebirdLocked within your own cryptographic signing engine HSM
Governance & Four-EyesUnilateral single-dev publishingMandatory Maker-Checker dual control for prod
Country Geo-FencingNo territorial filteringISO Country code whitelist (e.g. Cameroon, Ivory Coast)
Multi-Factor Auth (2FA)Relies on public Google/GitHub loginsHardened CSPRNG OTP 2FA + Enterprise SMTP relay
Cost ModelMetered per-patch and per-request billingPredictable enterprise licensing, unlimited traffic

2. Step-by-Step Migration Workflow​

Shorebird Cloud Migration Steps
  1. Register Project: Create your application in the TkushPatch Web Console.
  2. Update shorebird.yaml: Point base_url to your private TkushPatch server.
  3. Update Dependencies: Switch mobile packages to tk_ota_push.
  4. Verification: Build a base release and incremental patch to confirm sovereign delivery.

Step 1: Provisioning the Application on TkushPatch​

  1. Authenticate into your TkushPatch web console (https://console.tkushpatch.domain.com).
  2. Click New Project (CreateProjectModal).
  3. Enter your application name and Store bundle identifier (e.g., com.enterprise.banking).
  4. The system assigns a sovereign app_id (e.g., 8f2c3d10-4e5a-4b91-a8d2-11e4f901c238) and generates isolated RSA signing keypairs inside cryptographic signing engine.

Step 2: Updating shorebird.yaml​

In your Flutter project root, edit shorebird.yaml to point toward your sovereign cluster:

# Before (Shorebird Cloud)
# app_id: shorebird-cloud-id-12345

# After (Sovereign TkushPatch)
app_id: 8f2c3d10-4e5a-4b91-a8d2-11e4f901c238
base_url: https://api.tkushpatch.domain.com

[!IMPORTANT] The base_url key instructs both the CLI and client runtime engine to interact exclusively with your self-hosted backend. No telemetry or requests will ever route to Shorebird servers.

Step 3: Swapping Dependencies in pubspec.yaml​

Replace the Shorebird package with the tk_ota_push SDK:

dependencies:
  flutter:
    sdk: flutter
  # Remove: shorebird_code_push: ^x.y.z
  # Add:
  tk_ota_push: ^1.2.0

Update your Dart file imports:

// Before
// import 'package:shorebird_code_push/shorebird_code_push.dart';

// After
import 'package:tk_ota_push/tk_ota_push.dart';

Step 4: Compiling the Store Transition Release​

Because TkushPatch private keys differ cryptographically from Shorebird-managed keys, existing field devices require a transitional Store release containing your new sovereign public key:

# Compile native binary release
tk-ota-push release android --artifact=aab
  1. Submit this app-release.aab to Google Play Console or Apple App Store.
  2. Roll out the release to your user base.
  3. Once users install this baseline, their handsets automatically begin polling your TkushPatch server.

Step 5: Publishing and Certifying Your First Sovereign Patch​

With the transition release published, deploy an initial patch to validate pipeline integrity:

tk-ota-push patch android --release-version=2.0.0+1 --track=staging
  1. Open the /approvals dashboard in your web console.
  2. Review the quarantined patch and sign it with cryptographic signing engine.
  3. Confirm reception on a QA test device.
  4. Once QA certifies the update, promote it to stable in 1 click.