How to Build a Mattermost Android app

At times, you may want to build your own Mattermost mobile app. The most common use cases are:

• To white label the Mattermost mobile app.
• To use your own deployment of the Mattermost Push Notification Service (always required if you are building your own version of the mobile app).

Build Preparations 

1. Package name and source files 

• Ensure the package ID of the mobile app remains the same as the one in the original mattermost-mobile GitHub repository in com.mattermost.rnbeta.
• Source files for the main package remain under the android/app/src/main/java/com/mattermost/rnbeta folder.

2. Generating a signing key 

As Android requires all apps to be digitally signed with a certificate before they can be installed building the Android app for distribution requires the release APK to be signed.

To generate the signed key, use keytool which comes with the JDK required to develop the Android app. (see Developer Setup).

$ keytool -genkey -v -keystore <my-release-key>.keystore -alias my-key-alias -keyalg RSA -keysize 2048 -validity 10000

The above command prompts you for passwords for the keystore and key (make sure you use the same password for both), and asks you to provide the Distinguished Name fields for your key. It then generates the keystore as a file called <my-release-key>.keystore.

The keystore contains a single key, valid for 10000 days. The alias is a name that you will use later when signing your app, so remember to take a note of the alias.

Note:

• Replace <my-release-key> with the filename you want to specify.
• Remember to keep your keystore file private and never commit it to version control.

3. Create a new app in Google Play 

Create a new application using the Google Play console. If you already have an app registered in the Google Play console you can skip this step.

4. Setting up Gradle Variables 

Now that we have created the keystore file we can tell the build process to use that file:

• Copy or move the my-release-key.keystore file under a directory that you can access. It can be in your home directory or anywhere in the file system.

• Edit the gradle.properties file in your $HOME directory (e.g. $HOME/.gradle/gradle.properties), or create it if one does not exist, and add the following:

  MATTERMOST_RELEASE_STORE_FILE=/full/path/to/directory/containing/my-release-key.keystore
  MATTERMOST_RELEASE_KEY_ALIAS=my-key-alias
  MATTERMOST_RELEASE_PASSWORD=*****
  

Note:

• Replace /full/path/to/directory/containing/my-release-key.keystore with the full path to the actual keystore file and ******** with the actual keystore password.
• Back up your keystore and don’t forget the password.

Important:

Once you publish the app on the Play Store, the app needs to be signed with the same key every time you want to distriibute a new build. If you lose this key, you will need to republish your app under a different package id (losing all downloads and ratings).

5. Configure environment variables 

To make it easier to customize your build, we’ve defined a few environment variables that are going to be used by Fastlane during the build process.

Note: To configure your variables create the file ./mattermost-mobile/fastlane/.env where .env is the filename. You can find the sample file env_vars_example here.

6. Google Services 

Replace the google-services.json file as instructed in the Android Push Notification Guide before you build the app.

Building the App 

Once all the previous steps are done, execute the following command from within the project’s directory:

$ npm run build:android

This will start the build process following the environment variables you’ve set. Once it finishes, it will create the .apk file(s) with the APP_NAME as the filename in the project’s root directory. If you have not set Fastlane to submit the app to the Play Store, you can use this file to manually publish and distribute the app.