Skip to main content

Self-hosted Live Updates Setup

note

This feature is only available on our Enterprise plan. Contact us to get started today.

Overview​

For our customers with strict security requirements, Self-hosted Live Updates includes enhanced security features built on top of Appflow's already secure delivery mechanisms.

Self-hosted Live Updates allows customers to build and host their web artifacts then deploy them as Live Updates to app users. To help ensure secure end-to-end delivery, code signing and signature verification steps are included as well.

This guide outlines the one-time setup process for Self-hosted Live Updates and instructions on how to include them within your existing CI/CD pipeline.

Requirements​

Mobile:

  • Capacitor v5+. Need Cordova support? Check out the original Live Update solution featuring Appflow-hosted live updates only.
  • User devices running iOS 13+ or Android 5.1+.

Cloud infrastructure:

  • High-availability servers that can handle low to medium levels of traffic (varies based on number of app users). Any modern CI/CD platform will suffice, such as AWS, Azure DevOps, Jenkins, etc.
  • Integration of the Ionic Cloud CLI into a pre-existing or new CI/CD pipeline.
  • Hosting of the web build artifacts in Appflow or your cloud storage provider of choice (such as AWS S3 buckets or Azure Storage Blobs)
  • [Optional] Leveraging a CDN to distribute live updates around the world and enable faster downloads to end users of your apps

Workflow​

Much of the self-hosted live update process is completed within your CI/CD infrastructure, with Appflow and a live update plugin managing the deployments of live updates.

Self-hosted live updates workflow

Beginning in your CI/CD system, a web build is performed. The web build is packaged up into a live update bundle and signed with a private key using the Ionic Cloud CLI. Next, the live update is uploaded to your storage provider of choice. Then, the live update is registered with Appflow so it knows that a new live update is available. Various metadata is shared with Appflow such as the web URL of the live update. Finally, the live update can be deployed immediately if desired using the Ionic Cloud CLI.

Customers can choose to deploy the live update at a later time using the Appflow web UI. Within Appflow, the same capabilities of the classic live update solution are available, including viewing the complete list of live updates, the ability to set native versioning restrictions, and even rollback to previous live updates.

When an app user reopens your mobile app, the live update plugin calls back to Appflow to see if a new live update is available. If it is, it is downloaded to the device. Using a public key embedded in the app, the live update bundle is verified. If the contents are successfully verified, the live update is applied to the mobile app. The next time the user opens the app they will see the new live update changes.

App Setup​

The following steps explain the one-time setup process required to configure your app.

Create an App in Appflow​

While much of these features are performed within your infrastructure, Appflow still needs to be aware of your app. You'll also manage live update deployments and channels from within the Appflow dashboard. On the Apps screen within Appflow, click the New button then choose "Import existing app." Enter your app's name, select Capacitor as the mobile architecture, then click "Connect git host later." You won't connect your app's code to Appflow at any point.

With the app created, note the APP ID that appears at the top of the screen, like "042a1261." You'll need it shortly.

Download and Configure the Ionic Cloud CLI​

Use of Self-hosted Live Updates requires using the Ionic Cloud CLI for signing, bundling, and uploading Live Update artifacts. It can also generate signing keys for you if you need it to. The Ionic Cloud CLI was purpose-built for use within CI/CD systems; it's small and easy to download. Please reference the one-line install instructions.

You'll also need to supply the Ionic Cloud CLI with a Personal Access Token for authentication with your Appflow account. The Ionic Cloud CLI documentation outlines the available configuration options.

Code Signing: Generate Live Update Signing Keys​

Code signing guarantees that the code your developers wrote is the code that is shipped and applied to user devices. Each Live Update web artifact is signed with your private key, then the Live Updates plugin uses the public key to verify integrity of the new update. It is only applied to the user's device if nothing has been modified.

The Ionic Cloud CLI includes a command for generating signing keys. This command generates a public and private key pair. The key files are written to the current working directory; these files can be named by passing additional arguments to the following command.

ionic-cloud live-update generate-signing-key

The private key is used by the Ionic Cloud CLI to sign the Live Update artifact before uploading the artifact to Appflow. The public key needs to be published with your app via the Live Update plugin configuration to verify the signature of the Live Update artifact upon download.

Code Signing: Store Your Private Key​

You only need to generate your signing keys once, so once you've generated your key pair, make sure you store your private key somewhere secure and durable. If your private key is lost, you will need to generate a new signing key pair and publish the new public key to your app via a native binary release.

Make sure you also store the private key somewhere that is accessible from your CI/CD system. The private key will need to be passed to the Ionic Cloud CLI each time you upload a new Live Update artifact.

note

While it is technically possible to use the same signing keys for multiple apps, we recommend using unique signing keys for each of your apps.

Install The Live Update Plugin​

Within your Capacitor app project, install the Live Update plugin:

npm install @capacitor/live-updates
npx cap sync

Configure Live Updates​

With the live update plugin installed, add a "LiveUpdates" configuration section under plugins in capacitor.config.ts (or capacitor.config.json) file. Set appId with the Appflow app id created above, channel to the live update channel that the plugin should listen to for new updates, autoUpdateMethod to "background" to have live updates download in the background and automatically apply the next time the user opens the app, and maxVersions to the maximum number of versions of the app to keep cached on device. The key is the path to the public key created above used to verify the signature of the Live Update artifact upon download. It is recommended to store the public key file at the root of the Capacitor project. strategy refers to the manner in which a live update is generated, either differential for consisting of only the modified files from previous updates (recommended and the default) or zip a zip file containing the entire application.

note

If Appflow hosts your live update artifacts, you must set strategy to 'zip'.

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  appId: 'com.company.appname',
  appName: 'My Capacitor App',
  webDir: 'www',
  plugins: {
    LiveUpdates: {
      appId: '042a1261',
      channel: 'production',
      autoUpdateMethod: 'background',
      maxVersions: 2,
      strategy: 'differential',
      key: 'public_key.pem'
    }
  }
};

export default config;

With the live updates plugin configuration details set (and anytime you change the configuration in the future), sync the project to ensure the iOS and Android native projects are updated:

npx cap sync

Choosing a Live Update Strategy​

There are multiple strategies to choose from when applying new live updates, the first being background mode. The app will check for updates in the background and not prolong the amount of time the splash screen is shown. If an update is available, it will be downloaded and installed while the user is using the older version. The next time the app is launched the new live update will be applied. Set autoUpdateMethod: 'background' in capacitor.config.ts to use background mode.

Alternatively, you can use the Live Update plugin API to directly control when live updates are downloaded and when they are applied. In this example, we'll download live updates in the background while the app is in use and reload the app immediately after the user opens the app the next time, whether relaunched or after switching between apps. This is the best approach for ensuring your app users are (almost) always on the latest version.

First, set (autoUpdateMethod: 'none') in capacitor.config.ts then install the Capacitor App plugin. We'll use the resume event to fire an event when the app enters the foreground.

npm install @capacitor/app
npx cap sync

Next, add the following code wherever your app startup code is. On app load, it calls LiveUpdates.sync() to check for a new live update and download it. Once the sync call has finished, the activeApplicationPathChanged property is inspected and value saved to Local Storage. This will only be set to true if a new live update was downloaded.

import * as LiveUpdates from '@capacitor/live-updates';

async initializeApp() {
  // Register event to fire each time user resumes the app  
  App.addListener('resume', async () => {
    if (localStorage.shouldReloadApp) {
      await LiveUpdates.reload();
    }
    else {
      const result = await LiveUpdates.sync();
      localStorage.shouldReloadApp = result.activeApplicationPathChanged;
    }
  });

  // First sync on app load
  const result = await LiveUpdates.sync();
  localStorage.shouldReloadApp = result.activeApplicationPathChanged;
}

Eventually, an app user will close your app or switch to another one. When they come back to your app, the resume event will fire. Immediately after this, shouldReloadApp is checked from Local Storage. If true, the app is reloaded before the user has a chance to use the app, updating them to the latest version. If false, another sync() call is made and again the activeApplicationPathChanged property is inspected and saved to Local Storage.

The above solution will always reload the app when a live update is available. This could be problematic if it interrupts a user's workflow such as when filling out a form or logging in. To minimize this, consider including a shouldBlockReload check placed before any critical workflows that are about to happen. In this example, we toggle it to true right before logging in using Auth Connect then false after the user has authenticated successfully.

public async login() {
  localStorage.shouldBlockReload = true;
  await AuthConnect.login();
  localStorage.shouldBlockReload = false;
}

Then, within the resume listener, update the check that occurs before reloading the app to specify that the app should only be reloaded if there is a live update available and it shouldn't be blocked.

if (localStorage.shouldReloadApp && !localStorage.shouldBlockReload) {
  await LiveUpdates.reload();
};

Finally, customers who want to force the application of new live updates immediately on app load have another option. First, install the Capacitor Splash Screen plugin:

npm install @capacitor/splash-screen
npx cap sync

Next, in capacitor.config.ts set launchAutoHide to false, which will keep the splash screen visible until manually hidden.

const config: CapacitorConfig = {
  plugins: {
    SplashScreen: {
      launchAutoHide: false
    }
  }
};

Next, add the following code wherever your app startup code is. On app load, it calls LiveUpdates.sync() to check for a new live update and download it. Once the sync call has finished, the activeApplicationPathChanged property is inspected and value saved to Local Storage. This will only be set to true if a new live update was downloaded. If a new live update is available, it is applied as the app is reloaded. Otherwise, the splash screen is hidden and the user may use the app.

import { SplashScreen } from '@capacitor/splash-screen';
import * as LiveUpdates from '@capacitor/live-updates';

async initializeApp() {
  const result = await LiveUpdates.sync();
  if (result.activeApplicationPathChanged) {
    await LiveUpdates.reload();
  }
  else {
    await SplashScreen.hide();
  }
}

Copy Public Key into iOS Project​

Running the cap sync command will copy the public key into the Android project, but iOS requires a manual step to accomplish the same. Open Xcode (npx cap open ios) then open the project navigator. In the navigator window, right-click on "App" (the folder, not the top level App entry), then choose "Add files to App." Navigate to the public key and click Add. The public key will appear in the navigator, like so ("ionic_cloud_public.pem" in the screenshot):

Public key location in Xcode

Note that since the Live Updates plugin has been added to the app project, a new native version of the app needs to be deployed to the app store(s) before Live Updates can be used.

CI/CD Pipeline Setup​

The following sections outline the additional steps to add to your CI/CD pipeline to publish a Self-hosted Live Update to your app.

Build a Live Update​

Using your preferred CI/CD system, perform a build of your app's web resources.

Host the Live Update​

Customers can choose to have live update web artifacts stored and hosted in Appflow ("Appflow-hosted") or their cloud storage solution of choice ("self-hosted").

Appflow-hosted​

If you choose to have Appflow host your live update web artifacts, your app's build directory will be signed, bundled, and uploaded to Appflow.

note

If Appflow hosts your live update artifacts, you must set strategy in capacitor.config.ts to zip.

The Ionic Cloud CLI does the heavy lifting here:

ionic-cloud live-update upload-artifact 
  --app-id=APP_ID 
  --build-dir=DIR
  --commit-ref=BRANCH
  --commit-sha=SHA
  --commit-message=MESSAGE
  --signing-key=IONIC_SIGNING_KEY
  --token=TOKEN
  • app-id: The Appflow App Id created at the top of this guide, such as 042a1261.
  • build-dir: The directory where your compiled web app is found, such as www for Angular apps.
  • commit-ref: The branch name of the commit, such as "main" or "production."
  • commit-sha: The Git commit SHA, such as "adf9137y45".
  • commit-message: The Git commit message, such as "Fix login bug."
  • signing-key: Pass the entire private key as a string or the complete file path/name.
  • token: The Appflow personal access token.

Self-hosted​

If you choose to host live update web artifacts in your infrastructure, your app's build directory will be signed, bundled, and uploaded to your storage mechanism of choice. Finally, you'll inform Appflow that a new live update is available.

note

Complete pipeline examples are available, such as Azure DevOps.

Create a Signed Live Update​

Now that the web app has been built, we can use the Cloud CLI generate-manifest command to create a live update manifest file. The resulting live-update-manifest.json file includes a hash for every file in the compiled web app directory. If a native app has a live update manifest file, local files on disk are compared with the manifest and only changed files are downloaded. This makes the update much smaller and faster, resulting in improved performance over slower connections.

  • build-dir: The top-level build directory containing the compiled web app, such as www for an Angular app.
  • signing-key: The private key used to sign the live update.
  • token: The Appflow personal access token.
ionic-cloud live-update generate-manifest
  --build-dir=DIR 
  --token=TOKEN
  --signing-key=PRIVATE_KEY

Upload Live Update to Storage Provider​

With the new live update created, upload it your storage provider of choice. Steps will vary depending on your provider of choice (AWS S3, Azure data storage, etc.). See Azure data storage as an example.

If using the differential strategy (recommended), upload the entire application's files, including the live-update-manifest.json file generated in the previous step. If using the zip strategy, upload the entire application and live update manifest in a zip file.

Register Signed Live Update with Appflow​

In this last step, inform Appflow that a new live update is available with the Cloud CLI register-artifact command.

  • app-id: The Appflow App Id created at the top of this guide, such as 042a1261.
  • artifact-type: The type of artifact being registered, either zip or manifest for differential live updates.
  • artifact-url: The URL where the new live update artifact is stored. The Capacitor live update plugin will download the live update from your storage provider. When using manifest artifact-type, URL should end with live-update-manifest.json. When using zip artifact-type, URL should end with .zip.
  • token: The Appflow personal access token.
  • commit-ref: The branch name of the commit, such as "main" or "production."
  • commit-sha: The Git commit SHA, such as "adf9137y45".
  • commit-message: The Git commit message, such as "Fix login bug."
ionic-cloud live-update register-artifact 
  --app-id=APP_ID 
  --artifact-type=TYPE
  --artifact-url=URL
  --commit-ref=REF
  --commit-sha=SHA
  --commit-message=MESSAGE
  --token=TOKEN

With a new live update now hosted in either Appflow or your storage provider of choice, it's ready to be deployed to your app users!

Deploy the Live Update​

Upon completion, you'll find the new live update in your App's Builds list in Appflow. From there, you can follow the standard Live Update flow of assigning the build to a Live Update Channel.

Submit an edit