Package and Deploy Oracle JET Apps

22 Package and Deploy Oracle JET Apps

If you used Oracle JET tooling to create your Oracle JET app, you can package web apps for deployment to a web or app server and hybrid mobile apps for deployment to the Google Play or Apple App stores.

Package Web Apps

If you created your app using the tooling, use the Oracle JET command-line interface (CLI) to create a release version of your app containing your app scripts and applicable Oracle JET code in minified format.

From a terminal prompt in your app’s root directory, enter the following command: ojet build --release.

The command will take some time to complete. When it’s successful, you’ll see the following message: Build finished!.

The command replaces the development version of the libraries and scripts in web/js/ with minified versions where available.
To verify that the app still works as you expect, run ojet serve with the release option.
The ojet serve --release command takes the same arguments that you used to serve your web app in development mode.
```
ojet serve --release [--serverPort=server-port-number --serverOnly]
```
Tip:
For a complete list of options, type ojet help serve at the terminal prompt.

Deploy Web Apps

Oracle JET is a collection of HTML, JavaScript, and CSS files that you can deploy to any type of web or app server. There are no unique requirements for deploying Oracle JET apps.

Deployment methods are quite varied and depend upon the type of server environment your app is designed to run in. However, you should be able to use the same method for deploying Oracle JET apps that you would for any other client interface in your specific environment.

For example, if you normally deploy apps as zip files, you can zip the web directory and use your normal deployment process.

About Packaging and Publishing Hybrid Mobile Applications

The steps to package your app for release are broadly the same, irrespective of the platform where your app is going to be installed.

You create a build configuration file that identifies the location of your digital certificate, and then use the build configuration file as an input parameter to the ojet build command in order to sign your app with the digital certificate.

Before you proceed to signing and packaging your app for each platform where it will be used, review the entries in your app’s config.xml file, as described in Review Your App Settings in the config.xml File. Once you complete that task, proceed to the platform-specific instructions in the following sections.

Package a Hybrid Mobile App on Android

To prepare your app for distribution on Android devices, you need to sign it using a digital certificate and package it into an .APK file.

To sign an app that you want to release and publish through the Google Play Store or some other distribution mechanism, you need a unique key. Your organization may provide you with one, in which case you specify its location in the build configuration file that you use to sign and package your app. If you don’t have a key, you can create one that you use to sign your app. Subsequent updates to your app must be signed using the same key that you create. You can create a self-signed key using the JDK’s keytool utility or using the dialogs that Android Studio provides from its Build > Generate Signed APK menu. For more information about the latter option, see the “Generate a key and keystore” section in the Sign Your App page on the Android developer’s site.

Once you have generated your key, specify the location of its store, its alias, and its access credentials in your build configuration file, as shown by the following example.

{
  "android": {
    "release": {
      "keystore": "/home/pathTo/keystore/android.jks",
      "storePassword": "MyKeystorePassword",
      "alias": "myAndroidKey",
      "password" : "MyKeyPassword",
      "keystoreType": ""
    }
  }
}

You can now package your app into an .APK file (the installation file type for apps on Android devices).

At a terminal prompt, in your app’s top-level directory, enter the following command:

ojet build android --release --build-config=/pathTo/yourBuildConfig.json

On successful completion, the terminal window displays output similar to the following:

...

...
 Oracle JET CLI
Running "build:release" (build) task
Running "oraclejet-build:release" (oraclejet-build) task
 Oracle JET Tooling
cleaning staging path.....
...
BUILD SUCCESSFUL

Total time: 4.376 secs

Built the following apk(s):
        /appRootDir/hybrid/platforms/android/build/outputs/apk/android-release.apk
Cordova compile finished....

Done.

The build command outputs the .APK file that packages your app to the following location:

/appRootDir/hybrid/platforms/android/build/outputs/apk/android-release.apk.

Use this file to release your app through a public app marketplace, such as Google Play, a private app store, or some other means. End users who install your app from a location other than Google Play need to configure their device to opt in to install the app from an unknown source. For information about all these options, see https://developer.android.com/studio/publish/index.html#publishing-release.

Package a Hybrid Mobile App on iOS

To prepare your app for distribution on iOS devices, you need to sign it and package it into an .IPA file.

Joining the Apple Developer Program is the first step to submit your iOS app to the Apple App Store, to distribute an in-house app, or to sign an app that you distribute outside the Apple App Store. As a member, you have access to the resources you need to configure app services and to submit new apps and updates. For more information on the Apple Developer Program, see Apple Developer Program in Apple’s documentation.

Code signing your app allows users to trust that your app has been created by a source known to Apple and that it hasn’t been tampered with. All apps must be code signed and provisioned to deploy to an iOS device, to use certain Apple services, to be distributed for testing on iOS devices, or to be uploaded to the Apple App Store.

Signing identities are used to sign your app or installer package. A signing identity consists of a public-private key pair that Apple issues. The public-private key pair is stored in your keychain, and is used by cryptographic functions to generate the signature. A certificate stored in your developer account contains the associated public key. An intermediate certificate is also required to be in your keychain to ensure that your certificate is issued by a certificate authority.

Code signing requires that you have both the signing identity and the intermediate certificate installed in your keychain. When you install Xcode, Apple’s intermediate certificates are added to your keychain for you.

There are different types of certificates. A development certificate identifies a person on your team and is used to run an app on a single device. A distribution certificate identifies the team and is used to submit your app to the Apple App store or to distribute it outside of the store. Within an enterprise (organization) distribution certificates can be shared by team members in order to deploy various apps to a number of different devices. Certificates are issued and authorized by Apple.

If you are a member of an organization membership in the Apple Developer Program, you should request your team agent to provide your required signing identifies and certificates. Otherwise, you can create all the types of certificates and signing identities you need using the Apple Developer portal at https://developer.apple.com/account.

For more information on managing signing identities and certificates, see Code Signing in Apple’s documentation.

When you code sign an app, a provisioning profile is installed into the package that associates one or more certificates and one or more devices with an application ID. Provisioning profiles are created using the Apple Developer portal and must be downloaded and installed into Xcode on your development machine.

An application ID is a two-part string used to identify one or more apps from a single development team. The string consists of a Team ID and a bundle ID search string, with a period (.) separating the two parts. The Team ID is supplied by Apple and is unique to a specific development team, while the bundle ID search string is supplied by you to match either the bundle ID of a single app or a set of bundle IDs for a group of your apps.

Application IDs and devices are registered with your team account using the Apple Developer portal.

For more information on managing application IDs, devices and provisioning profiles, see Apple’s documentation.

Once you have created and installed the necessary code signing artifacts, specify the details in your build configuration file, as shown in the following example:

{
  "ios": {
    "debug": {
      "provisioningProfile": "My Developer Provisioning Profile ID",
      "developmentTeam": "My Team ID",
      "codeSignIdentity": "iPhone Developer",
      "packageType": "development"
    },
    "release": {
      "provisioningProfile": "My Distribution Provisioning Profile ID",
      "developmentTeam": "My Team ID",
      "codeSignIdentity": "iPhone Distribution",
      "packageType": "enterprise"
    }
  }
}

At time of writing, Apache Cordova does not support the new build system that Xcode 10, the latest release of Xcode, uses by default. If you use Xcode 10, you can work around this issue until Apache Cordova supports Xcode 10 by including the buildFlag command-line argument in your build configuration file, as demonstrated by the following example, so that the older build system builds your app.

{
     ...
      "codeSignIdentity": "iPhone Distribution",
      "packageType": "enterprise",
      "buildFlag": [
        "-UseModernBuildSystem=0"
      ]
    }
  }
}

You can now package your app into an .IPA file (the installation file type for apps on iOS devices).

At a terminal prompt, in your app’s top-level directory, enter the following command:

ojet build ios --device --release --build-config=/pathTo/yourBuildConfig.json

On successful completion, the terminal window displays output similar to the following:

...
** ARCHIVE SUCCEEDED **


Exported appName.xcarchive to: appDir/hybrid/platforms/ios/build/device

** EXPORT SUCCEEDED **


Cordova compile finished....

Done.

The resulting .IPA file will be located at:

appDir/hybrid/platforms/ios/build/device/appName.ipa

This file can be deployed to an iOS device that matches the installed provisioning profile using iTunes, or you can release your app through the public marketplace, Apple App Store, a private app store, or some other means. For information about submitting your app to the Apple App Store, see Distribute an app through the App Store in Apple’s documentation.

Remove and Restore Non-Source Files from Your JET App

The Oracle JET CLI provides commands (clean, strip, and restore) that manage the source code of your JET app by removing extraneous files, such as the build output for the platforms your JET app supports or npm modules installed into your project.

Consider using these commands when you want to package your source code for distribution to colleagues or others who may work on the source code with you. Use of these commands may not be appropriate in all circumstances. Use of the clean and strip commands will, for example, remove the build output for hybrid mobile apps that includes the installation files to install the app on a user’s device.

ojet clean

Use the ojet clean command to clean the build output of your JET app. Specify the appropriate parameter with the ojet clean command to clean the build output on the platform(s) that your JET app supports (android, ios, and web). This command can be useful when developing a hybrid mobile app that makes use of staging files as you can make sure that all staging files are removed between builds. These staging files will be regenerated the next time that you build or serve the hybrid mobile app. Run the following command in your app’s top level directory to clean the output of your app that targets the Android platform:

ojet clean android

Similarly, run ojet clean web to remove the contents of your app’s root directory’s web directory.

ojet strip

Use ojet strip when you want to remove all non-source files from your JET app. In addition to the build output removed by the ojet clean command, ojet strip removes additional dependencies, such as Cordova plugins, and npm modules installed into your project. A typical usage scenario for the ojet strip command is when you want to distribute the source files of your JET app to a colleague and you want to reduce the number of files to transmit to the minimum.

The ojet strip command relies on the presence of the .gitignore file in the root directory of your app to determine what to remove. The file lists the directories that are installed by the tooling and can therefore be restored by the tooling. Only those directories and files listed will be removed when you run ojet clean on the app folder.

If you do not use Git and you want to run ojet strip to make a project easier to transmit, you can create the .gitignore file and add it to your app's root folder with a list of the folders and files to remove, like this:

#List of web app folders to remove
/node_modules
/bower_components
/themes
/web

#List of hybrid mobile app folders to remove
/hybrid
/node_modules
/hybrid/platforms
/hybrid/www

#List of exceptions not to remove from above folder list
!hybrid/plugins
hybrid/plugins/*
!hybrid/plugins/fetch.json

As an alternative to the .gitignore file, you can include a stripList property that takes an array of glob pattern values in your app's oraclejetconfig.json file. When you specify the stripList parameter in the oraclejetconfig.json file, Oracle JET ignores the .gitignore file and its entries. Specify the list of directories and file types that you want to remove when you run ojet strip, as demonstrated by the following example.

{
. . .
  "generatorVersion": "13.0.0",
  "stripList": [
    "jet_components",
    "node_modules",
    "bower_components",
    "dist",
    "web",
    "staged-themes",
    "themes",
    "myfiles/*.txt"
  ]
}

ojet restore

Use the ojet restore command to restore the dependencies, plugins, libraries, and Web Components that the ojet strip command removes. After the ojet restore command completes, use the ojet build and/or ojet serve commands to build and serve your JET app.

The ojet restore command supports a number of additional parameters, such as ojet restore --ci that invokes the npm ci command instead of the default npm install command. This option (ojet restore --ci) fetches the dependencies specified in the package-lock.json file, and can be useful in CI/CD pipelines.

For additional help with CLI commands, enter ojet help at a terminal prompt.