[pkg] improve osx installer

- install into global /Applications
- document how to troubleshoot helper
- uninstall app is visible on top-level folder
- improve detection of running processes for old and new binaries

- Closes: #441
- Closes: #445
- Closes: #435

2 files changed, 63 insertions, 3 deletions

diff --git a/docs/build.osx.rst b/docs/build.osx.rst
index 43d70ad..48836a7 100644
--- a/docs/build.osx.rst
+++ b/docs/build.osx.rst
@@ -9,11 +9,12 @@ have to sign and then notarize with their service. here are some notes that use
 ad-hoc targets in the main makefile, but we should keep an eye on any future
 integration of this process in the more or less official Qt tools (QTIFW).
 
-First, we build the regular installer
+First, we build the regular installer (use RELEASE=yes to do a codesign step
+with macqtdeploy, note that this increases build time considerably):
 
 ```
 make build
-make installer
+RELEASE=yes make installer
 make sign_installer
 ```
 
@@ -23,6 +24,18 @@ account. Contact their friendly support for more info, but don't expect they
 understand you do not really own any Apple Hardware. Sense of humor is not
 universal.
 
+Security -> App-specific passwords -> Generate
+If you need to revoke these tokens, click on 'view history'.
+
+https://appleid.apple.com/account/manage
+
+According to https://developer.apple.com/documentation/xcode/notarizing_macos_software_before_distribution/customizing_the_notarization_workflow:
+
+To avoid including your password as cleartext in a script, you can provide a
+reference to a keychain item, as shown in the previous example. This assumes
+the keychain holds a keychain item named AC_PASSWORD with an account value
+matching the username AC_USERNAME.
+
 ```
 export OSXAPPPASS=my-apple-app-pass
 make notarize_installer
@@ -37,7 +50,7 @@ altool[5281:91963] No errors uploading 'build/installer/RiseupVPN-installer-0.20
 RequestUUID = fe9a4324-bdcb-4c52-b857-f089dc904695
 
 OSXMORDORUID=fe9a4324-bdcb-4c52-b857-f089dc904695 make notarize_check
-xcrun altool --notarization-info fe9a4324-bdcb-4c52-b857-f089dc904695 -u "info@leap.se" -p nvaq-xdhq-wrho-ouuu
+xcrun altool --notarization-info fe9a4324-bdcb-4c52-b857-f089dc904695 -u "info@leap.se" -p my-apple-app-pass
 2020-12-11 22:21:59.940 altool[5787:96428] No errors getting notarization info.
 
    RequestUUID: fe9a4324-bdcb-4c52-b857-f089dc904695
diff --git a/docs/debug.rst b/docs/debug.rst
new file mode 100644
index 0000000..c746cf6
--- /dev/null
+++ b/docs/debug.rst
@@ -0,0 +1,47 @@
+Troubleshooting
+===============
+
+This document contains some useful debug information.
+
+OSX
+---
+If you're having troubles with old versions of RiseupVPN that did not have an
+uninstaller, and the new installer is not cleanly replacing the previous
+install, you might need to manually clean things up. You will need root access to
+stop the privileged helper.
+
+First, see if the helper is running:
+
+pgrep bitmask-helper
+
+To stop it:
+
+sudo launchctl unload /Library/LaunchDaemons/se.leap.bitmask-helper.plist
+
+To start it:
+
+sudo launchctl load /Library/LaunchDaemons/se.leap.bitmask-helper.plist
+sudo launchctl start /Library/LaunchDaemons/se.leap.bitmask-helper.plist
+
+Check that it's running:
+
+pgrep bitmask-helper
+
+Manually check that the web api is running, and that it reports a version that matches what you currently have installed:
+
+curl http://localhost:7171/version
+
+Also, you can check that the path near the end of the file /Library/LaunchDaemons/se.leap.bitmask-helper.plist
+matches the current path where you installed RiseupVPN.app.
+
+Cleaning up
+~~~~~~~~~~~
+If you have things messed up and you want to completely delete the bitmask-helper:
+
+sudo launchctl unload /Library/LaunchDaemons/se.leap.bitmask-helper.plist
+sudo rm -rf /Library/LaunchDaemons/se.leap.bitmask-helper.plist
+
+Make sure that "pgrep bitmask-helper" does not return any pid.
+
+Now you can move /Applications/RiseupVPN.app to the Trash, and launch a
+recent installer to get a clean install.