Metabase OS X App

NOTE: These instructions are only for packaging a built Metabase uberjar into Metabase.app. They are not useful if your goal is to work on Metabase itself; for development, please see our developers’ guide.

First-Time Configuration

Building

The following steps need to be done before building the Mac App:

1. Install XCode.

2. Add a JRE to the OSX/Metabase/jre

   You can download a copy of a JRE from https://adoptopenjdk.net/releases.html — make sure you download a JRE rather than JDK. Move the Contents/Home directory from the JRE archive into OSX/Metabase/jre. For example:

   wget https://github.com/AdoptOpenJDK/openjdk8-binaries/releases/download/jdk8u232-b09/OpenJDK8U-jre_x64_mac_hotspot_8u232b09.tar.gz
   tar -xzvf OpenJDK8U-jre_x64_mac_hotspot_8u232b09.tar.gz
   mv jdk8u232-b09-jre/Contents/Home/ OSX/Metabase/jre
   

   You are fine to use whatever the latest JRE version available is. I have been using the HotSpot JRE instead of the OpenJ9 one but it ultimately shouldn’t make a difference.

3. Copy Metabase uberjar to OSX resources dir

   cp /path/to/metabase.jar OSX/Resources/metabase.jar
   

   Every time you want to build a new version of the Mac App, you can simple update the bundled uberjar the same way.

At this point, you should try opening up the Xcode project and building the Mac App in Xcode by clicking the run button. The app should build and launch at this point. If it doesn’t, ask Cam for help!

Releasing

The following steps are prereqs for releasing the Mac App:

1. Install XCode command-line tools. In Xcode > Preferences > Locations select your current Xcode version in the Command Line Tools drop-down.

2. Install CPAN modules

   sudo cpan
   install force File::Copy::Recursive Readonly String::Util Text::Caml JSON
   quit
   

   You can install PerlBrew if you want to install CPAN modules without having to use sudo.

   Normally you shouldn’t have to use install force to install the modules above, but File::Copy::Recursive seems fussy lately and has a failing test that prevents it from installing normally.

3. Install AWS command-line client (if needed)

   brew install awscli
   

4. Configure AWS Credentials for metabase profile (used to upload artifacts to S3)

   You’ll need credentials that give you permission to write the metabase-osx-releases S3 bucket. You just need the access key ID and secret key; use the defaults for locale and other options.

   aws configure --profile metabase
   

5. Obtain a copy of the private key for signing app updates (ask Cam) and put a copy of it at OSX/dsa_priv.pem

   cp /path/to/private/key.pem OSX/dsa_priv.pem
   

6. Add Apple Developer ID Application Certificate to your computer’s keychain.

   You’ll need to generate a Certificate Signing Request from Keychain Access, and have Sameer go to the Apple Developer Site and generate one for you, then load the file on your computer.

7. Export your Apple ID for building the app as METABASE_MAC_APP_BUILD_APPLE_ID. (This Apple ID must be part of the Metabase org in the Apple developer site. Ask Cam or Sameer to add you if it isn’t.)

   #  Add this to .zshrc or .bashrc
   export METABASE_MAC_APP_BUILD_APPLE_ID=my_email@whatever.com
   

8. Create an App-Specific password for the Apple ID in the previous step

   Go to https://appleid.apple.com/account/manage then Security > App-Specific Passwords > Generate Password

   1. Store the password in Keychain

      xcrun altool \
      --store-password-in-keychain-item "METABASE_MAC_APP_BUILD_PASSWORD" \
      -u "$METABASE_MAC_APP_BUILD_APPLE_ID" \
      -p <secret_password>
      

Building & Releasing the Mac App

After following the configuration steps above, to build and release the app you can use the ./bin/osx-release script:

1. Copy latest uberjar to the Mac App build directory

    cp path/to/metabase.jar OSX/Resources/metabase.jar
   

2. Bundle entire app, and upload to s3

    ./bin/osx-release
   

Debugging ./bin/osx-release

• You can run individual steps of the release script by passing in the appropriate step subroutines. e.g. ./bin/osx-release create_dmg upload. The entire sequence of different steps can be found at the bottom of ./bin/osx-release.
• Generating the DMG seems to be somewhat finicky, so if it fails with a message like “Device busy” trying the step again a few times usually resolves the issue. You can continue the build process from the DMG creation step by running ./bin/osx-release create_dmg upload.