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.

note

Self-hosted live updates require Capacitor v3+. User devices must be running iOS 13+ and Android 5.1+. Need Cordova support? Check out the original Live Update solution featuring Appflow-hosted live updates only.

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.

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,
      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

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. 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 bundle-artifact command to turn the web artifact into a live update.

  • 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.
  • output-path: The location and filename to store the live update.
  • token: The Appflow personal access token.
ionic-cloud live-update bundle-artifact 
  --build-dir=DIR 
  --token=TOKEN
  --signing-key=PRIVATE_KEY
  --output-path=FILENAME

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.

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-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.
  • 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-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.