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](developers-guide.md).
## Prereqs
## First-Time Configuration
1. Install XCode.
### Building
1. Install XCode command-line tools. In `Xcode` > `Preferences` > `Locations` select your current Xcode version in the `Command Line Tools` drop-down.
The following steps need to be done before building the Mac App:
1.Run `./bin/build` to build the latest version of the uberjar.
1.Install XCode.
1.Next, you'll need to run the following commands before building the app for the first time. You only need to do these once:
1.Add a JRE to the `OSX/Metabase/jre`
1. Install Git submodule
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:
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.
1. Copy Metabase uberjar to OSX resources dir
```bash
sudo cpan
install force File::Copy::Recursive Readonly String::Util Text::Caml JSON
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!
You can install [PerlBrew](https://perlbrew.pl/) if you want to install CPAN modules without having to use `sudo`.
### Releasing
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.
The following steps are prereqs for releasing the Mac App:
1. 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:
1. Install XCode command-line tools. In `Xcode` > `Preferences` > `Locations` select your current Xcode version in the `Command Line Tools` drop-down.
1. Install CPAN modules
```bash
sudo cpan
install force File::Copy::Recursive Readonly String::Util Text::Caml JSON
quit
```
You can install [PerlBrew](https://perlbrew.pl/) 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.
1. Install AWS command-line client (if needed)
```bash
brew install awscli
```
1. 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.
```bash
aws configure --profile metabase
```
1. Obtain a copy of the private key for signing app updates (ask Cam) and put a copy of it at `OSX/dsa_priv.pem`
```bash
cp /path/to/private/key.pem OSX/dsa_priv.pem
```
1. 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](https://developer.apple.com/account/mac/certificate/) and generate one for you, then load the file on your computer.
1. 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.)
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.
## Releasing
A handy Perl script called `./bin/osx-release` takes care of all of the details for you. Before you run it for the first time, you'll need to set up a few additional things:
```bash
# Install aws command-line client (if needed)
brew install awscli
# Configure AWS Credentials
# 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
# Obtain a copy of the private key used for signing the app (ask Cam)
# and put a copy of it at ./dsa_priv.pem
cp /path/to/private/key.pem OSX/dsa_priv.pem
```
You'll need the `Apple Developer ID Application Certificate` in 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](https://developer.apple.com/account/mac/certificate/)
and generate one for you, then load the file on your computer.
Finally, you may need to open the project a single time in Xcode to make sure the appropriate "build schemes" are generated (these are not checked into CI).
Run `open OSX/Metabase.xcodeproj` to open the project, which will automatically generate the appropriate schemes. This only needs to be done once.
After that, you are good to go:
```bash
# Build the latest version of the uberjar and copy it to the Mac App build directory
