From 9d9da92cb0ce64600664a24a6b7b07f2edba51eb Mon Sep 17 00:00:00 2001 From: "kali kaneko (leap communications)" Date: Fri, 5 Mar 2021 12:35:45 +0100 Subject: [docs] rename docs for coherence --- docs/build-osx.rst | 91 +++++++++++++++++++++++++++++++++++++++++++ docs/build-snap-launchpad.rst | 13 +++++++ docs/build-snap-release.rst | 58 +++++++++++++++++++++++++++ docs/build-win.rst | 57 +++++++++++++++++++++++++++ docs/build.osx.rst | 91 ------------------------------------------- docs/build.windows.rst | 57 --------------------------- docs/snap-launchpad.rst | 13 ------- docs/snap-release.rst | 58 --------------------------- 8 files changed, 219 insertions(+), 219 deletions(-) create mode 100644 docs/build-osx.rst create mode 100644 docs/build-snap-launchpad.rst create mode 100644 docs/build-snap-release.rst create mode 100644 docs/build-win.rst delete mode 100644 docs/build.osx.rst delete mode 100644 docs/build.windows.rst delete mode 100644 docs/snap-launchpad.rst delete mode 100644 docs/snap-release.rst diff --git a/docs/build-osx.rst b/docs/build-osx.rst new file mode 100644 index 0000000..32ba29d --- /dev/null +++ b/docs/build-osx.rst @@ -0,0 +1,91 @@ +osx build +============= + +Cheat-sheet +------------------ + +tl;dr: + +.. code:: bash + + export RELEASE=yes + export OSXAPPPASS=my-apple-app-pass + make clean && make vendor && make build + make installer + make sign_installer + make notarize_installer + make notarize_staple + make create_dmg + +Sign the release +------------------- + +in recent osx releases, it's not ok to just sign the insallers anymore. you +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 (use RELEASE=yes to do a codesign step +with macqtdeploy, note that this increases build time considerably): + +.. code:: bash + + make build + RELEASE=yes make installer + make sign_installer + +Now we export the app-specific password and we proceed to notarization. If you +don't know what is this pass, you can create one in your Apple developer +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. + +.. code:: bash + + export OSXAPPPASS=my-apple-app-pass + make notarize_installer + +Between the output of the last command, you will get a Request UUID. You should pass that request uid in the appropriate +environment variable to check the status of the notarization process. Obviously, since the recent changes in Apple policies, +you need to be in posession of a valid membership + +.. code:: bash + + altool[5281:91963] No errors uploading 'build/installer/RiseupVPN-installer-0.20.4-175-gee4eb90.zip'. + 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 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 + Date: 2020-12-11 21:13:10 +0000 + Status: success + LogFileURL: https://osxapps-ssl.itunes.apple.com/itunes-assets/Enigma114/v4/0f/c9/1e/0fc91e64-2c9f-74e5-3cf6-96b8f3bf7170/developer_log.json?accessKey=1607916119_6680812212684569509_nLlPw6tYxTSiWZfFTb0atP9zZ3CEGDfW0btWV51xhjWHiCFqBt%2BneXd5Vp40eQCSx8e1W5PYCIe2db7JGbhoTeJsYxl7UmYssRvYpTxYJl8z90uwB9jkbS1fsd7niaAn%2BQs7xHdv%2BB9jaKQI8LJ%2BwYY8RPq1QaeCJxBIdeG44DY%3D + Status Code: 0 + Status Message: Package Approved + +If everything is ok, now you can finish the process, stapling the notarization info and creating the dmg. + +.. code:: bash + + make notarize_staple + make create_dmg + +If everything went well, you should have a .dmg for your release under the `deploy` folder. + +.. code:: bash + + created: /Users/admin/leap/bitmask-vpn/deploy/RiseupVPN-0.20.4-175-gee4eb90.dmg diff --git a/docs/build-snap-launchpad.rst b/docs/build-snap-launchpad.rst new file mode 100644 index 0000000..0a614f6 --- /dev/null +++ b/docs/build-snap-launchpad.rst @@ -0,0 +1,13 @@ +launchpad +========= +In launchpad, you need to configure a git source for your project, and define a snap recipe for that source. + +Be warned that launchpad does an automatic import every 6 hours. + +If you need to do manual builds, you first need to trigger an import. Look for the "import now" button in your source page: + +https://code.launchpad.net/~leapsnaps/riseupvpn/+git/riseup_vpn + +Then you can trigger a manual build: + +https://code.launchpad.net/~leapsnaps/+snap/riseup-vpn/+request-builds diff --git a/docs/build-snap-release.rst b/docs/build-snap-release.rst new file mode 100644 index 0000000..7355d98 --- /dev/null +++ b/docs/build-snap-release.rst @@ -0,0 +1,58 @@ +Automatic builds (snap) +~~~~~~~~~~~~~~~~~~~~~~~ + +When properly configured (TBD), launchpad does up 4 daily builds if code is +modified in bitmask-dev repo. We're building for amd64 and i386. They are +pushed to beta channel in the snap store. If you need to force a build, +trigger it by editing the version string in the snapcraft.yaml file. + +Releasing snaps +---------------- + +From the snap dashboard, you can see the revisions that are built. +By default, we have riseupvpn-builds configured to upload builds to beta and +edge channels. If you are going to be pushing to edge manually regularly, +please configure the automated builds to push just to beta for some time and +push your builds to edge channel. + +To publish a snap, click on "release" from the dashboard, and assign a channel to them. + +By convention, if you release to a channel, please release the revision to all +the lower channels too. (For example, if you release a particular revision to +"candidate", release it also to "beta" and "edge"). + +Do note that the automated builds for different architectures do have different revision +numbers, so when releasing you have to repeat the steps for each platform that +we're building for. + +From the command line: + + snapcraft login + snapcraft status riseup-vpn + + # if we've built a release manually, we have to push it first. it gives us a + # revision number that we use in the next step. + + snapcraft upload riseup-vpn_0.10.6+git_amd64.snap + Preparing to push '/home/kali/leap/bitmask-dev/riseup-vpn_0.10.6+git_amd64.snap' to the store. + Found cached source snap /home/kali/.cache/snapcraft/projects/riseup-vpn/snap_hashes/amd64/b5e9d106c823e3c83fce1ef81ad95d68c33fcada859eeb98233fc766863d39205c192fe5ee53def71c43886e40d3ab5b. + Generating xdelta3 delta for riseup-vpn_0.10.6+git_amd64.snap. + Pushing delta /home/kali/leap/bitmask-dev/riseup-vpn_0.10.6+git_amd64.snap.xdelta3. + Pushing riseup-vpn_0.10.6+git_amd64.snap.xdelta3 [=================================================] 100% + Processing...| + Ready to release! + Revision 20 of 'riseup-vpn' created. + + # otherwise I assume that you're just trying to release something + # that was already built and automatically uploaded. + + # let's publish amd64 to candidate channel and the channels below + snapcraft release riseup-vpn 20 candidate + snapcraft release riseup-vpn 20 beta + snapcraft release riseup-vpn 20 edge + + # and now the i386 build + snapcraft release riseup-vpn 19 candidate + snapcraft release riseup-vpn 19 beta + snapcraft release riseup-vpn 19 edge + diff --git a/docs/build-win.rst b/docs/build-win.rst new file mode 100644 index 0000000..1e65c27 --- /dev/null +++ b/docs/build-win.rst @@ -0,0 +1,57 @@ +windows build +============= + +The build currently expects MINGW64 environment, on a native windows host. +A cross-compiling procedure (at least for the application binaries) should be possible in the near future, using mxe. (There's already some support for it in `gui/build.sh`). + +You should instal: make, wget, as well as a recent Qt5 version (for instance, with chocolatey: choco install make && choco install wget). + +(In order to avoid makefiles, you are welcome to submit a port of the build scripts using powershell or cscript - see the build.wsf script in openvpn-build for inspiration). + +For the installer, install QtIFW for windows (tested with version 3.2.2). + +Assuming you have the vendor path in place and correctly configured, all you need to do is `make installer`:: + + export PATH="/c/Qt/Qt5/bin/":"/c/Qt/QtIFW-3.2.2/bin":$PATH + export VENDOR_PATH=providers + export PROVIDER=riseup + make generate # FIXME this is not called in win + make vendor && make installer + +If you're doing a final release:: + + export RELEASE=yes + + +checking signatures +------------------- +we should be signing all binaries on a release build. + +to check the binaries have proper signatures, you can use the sigcheck +utilities, part of the sysinternals suite: + +https://docs.microsoft.com/en-us/sysinternals/downloads/sysinternals-suite + +unzip and place sigcheck.exe somewhere in your path. + +make sure to pass -accepteula parameter on some manual run so that it does not +ask again. + +adding metadata to binaries +--------------------------- + +the steps to do release signatures are:: + + make build + make dosign + make installer + make sign_installer + +or all together as:: + + make package_win_release + + +unreviewed notes +---------------- +see comment about patching dlls and windeployqt not being needed anymore https://stackoverflow.com/a/61910592 diff --git a/docs/build.osx.rst b/docs/build.osx.rst deleted file mode 100644 index 32ba29d..0000000 --- a/docs/build.osx.rst +++ /dev/null @@ -1,91 +0,0 @@ -osx build -============= - -Cheat-sheet ------------------- - -tl;dr: - -.. code:: bash - - export RELEASE=yes - export OSXAPPPASS=my-apple-app-pass - make clean && make vendor && make build - make installer - make sign_installer - make notarize_installer - make notarize_staple - make create_dmg - -Sign the release -------------------- - -in recent osx releases, it's not ok to just sign the insallers anymore. you -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 (use RELEASE=yes to do a codesign step -with macqtdeploy, note that this increases build time considerably): - -.. code:: bash - - make build - RELEASE=yes make installer - make sign_installer - -Now we export the app-specific password and we proceed to notarization. If you -don't know what is this pass, you can create one in your Apple developer -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. - -.. code:: bash - - export OSXAPPPASS=my-apple-app-pass - make notarize_installer - -Between the output of the last command, you will get a Request UUID. You should pass that request uid in the appropriate -environment variable to check the status of the notarization process. Obviously, since the recent changes in Apple policies, -you need to be in posession of a valid membership - -.. code:: bash - - altool[5281:91963] No errors uploading 'build/installer/RiseupVPN-installer-0.20.4-175-gee4eb90.zip'. - 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 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 - Date: 2020-12-11 21:13:10 +0000 - Status: success - LogFileURL: https://osxapps-ssl.itunes.apple.com/itunes-assets/Enigma114/v4/0f/c9/1e/0fc91e64-2c9f-74e5-3cf6-96b8f3bf7170/developer_log.json?accessKey=1607916119_6680812212684569509_nLlPw6tYxTSiWZfFTb0atP9zZ3CEGDfW0btWV51xhjWHiCFqBt%2BneXd5Vp40eQCSx8e1W5PYCIe2db7JGbhoTeJsYxl7UmYssRvYpTxYJl8z90uwB9jkbS1fsd7niaAn%2BQs7xHdv%2BB9jaKQI8LJ%2BwYY8RPq1QaeCJxBIdeG44DY%3D - Status Code: 0 - Status Message: Package Approved - -If everything is ok, now you can finish the process, stapling the notarization info and creating the dmg. - -.. code:: bash - - make notarize_staple - make create_dmg - -If everything went well, you should have a .dmg for your release under the `deploy` folder. - -.. code:: bash - - created: /Users/admin/leap/bitmask-vpn/deploy/RiseupVPN-0.20.4-175-gee4eb90.dmg diff --git a/docs/build.windows.rst b/docs/build.windows.rst deleted file mode 100644 index 1e65c27..0000000 --- a/docs/build.windows.rst +++ /dev/null @@ -1,57 +0,0 @@ -windows build -============= - -The build currently expects MINGW64 environment, on a native windows host. -A cross-compiling procedure (at least for the application binaries) should be possible in the near future, using mxe. (There's already some support for it in `gui/build.sh`). - -You should instal: make, wget, as well as a recent Qt5 version (for instance, with chocolatey: choco install make && choco install wget). - -(In order to avoid makefiles, you are welcome to submit a port of the build scripts using powershell or cscript - see the build.wsf script in openvpn-build for inspiration). - -For the installer, install QtIFW for windows (tested with version 3.2.2). - -Assuming you have the vendor path in place and correctly configured, all you need to do is `make installer`:: - - export PATH="/c/Qt/Qt5/bin/":"/c/Qt/QtIFW-3.2.2/bin":$PATH - export VENDOR_PATH=providers - export PROVIDER=riseup - make generate # FIXME this is not called in win - make vendor && make installer - -If you're doing a final release:: - - export RELEASE=yes - - -checking signatures -------------------- -we should be signing all binaries on a release build. - -to check the binaries have proper signatures, you can use the sigcheck -utilities, part of the sysinternals suite: - -https://docs.microsoft.com/en-us/sysinternals/downloads/sysinternals-suite - -unzip and place sigcheck.exe somewhere in your path. - -make sure to pass -accepteula parameter on some manual run so that it does not -ask again. - -adding metadata to binaries ---------------------------- - -the steps to do release signatures are:: - - make build - make dosign - make installer - make sign_installer - -or all together as:: - - make package_win_release - - -unreviewed notes ----------------- -see comment about patching dlls and windeployqt not being needed anymore https://stackoverflow.com/a/61910592 diff --git a/docs/snap-launchpad.rst b/docs/snap-launchpad.rst deleted file mode 100644 index 0a614f6..0000000 --- a/docs/snap-launchpad.rst +++ /dev/null @@ -1,13 +0,0 @@ -launchpad -========= -In launchpad, you need to configure a git source for your project, and define a snap recipe for that source. - -Be warned that launchpad does an automatic import every 6 hours. - -If you need to do manual builds, you first need to trigger an import. Look for the "import now" button in your source page: - -https://code.launchpad.net/~leapsnaps/riseupvpn/+git/riseup_vpn - -Then you can trigger a manual build: - -https://code.launchpad.net/~leapsnaps/+snap/riseup-vpn/+request-builds diff --git a/docs/snap-release.rst b/docs/snap-release.rst deleted file mode 100644 index 7355d98..0000000 --- a/docs/snap-release.rst +++ /dev/null @@ -1,58 +0,0 @@ -Automatic builds (snap) -~~~~~~~~~~~~~~~~~~~~~~~ - -When properly configured (TBD), launchpad does up 4 daily builds if code is -modified in bitmask-dev repo. We're building for amd64 and i386. They are -pushed to beta channel in the snap store. If you need to force a build, -trigger it by editing the version string in the snapcraft.yaml file. - -Releasing snaps ----------------- - -From the snap dashboard, you can see the revisions that are built. -By default, we have riseupvpn-builds configured to upload builds to beta and -edge channels. If you are going to be pushing to edge manually regularly, -please configure the automated builds to push just to beta for some time and -push your builds to edge channel. - -To publish a snap, click on "release" from the dashboard, and assign a channel to them. - -By convention, if you release to a channel, please release the revision to all -the lower channels too. (For example, if you release a particular revision to -"candidate", release it also to "beta" and "edge"). - -Do note that the automated builds for different architectures do have different revision -numbers, so when releasing you have to repeat the steps for each platform that -we're building for. - -From the command line: - - snapcraft login - snapcraft status riseup-vpn - - # if we've built a release manually, we have to push it first. it gives us a - # revision number that we use in the next step. - - snapcraft upload riseup-vpn_0.10.6+git_amd64.snap - Preparing to push '/home/kali/leap/bitmask-dev/riseup-vpn_0.10.6+git_amd64.snap' to the store. - Found cached source snap /home/kali/.cache/snapcraft/projects/riseup-vpn/snap_hashes/amd64/b5e9d106c823e3c83fce1ef81ad95d68c33fcada859eeb98233fc766863d39205c192fe5ee53def71c43886e40d3ab5b. - Generating xdelta3 delta for riseup-vpn_0.10.6+git_amd64.snap. - Pushing delta /home/kali/leap/bitmask-dev/riseup-vpn_0.10.6+git_amd64.snap.xdelta3. - Pushing riseup-vpn_0.10.6+git_amd64.snap.xdelta3 [=================================================] 100% - Processing...| - Ready to release! - Revision 20 of 'riseup-vpn' created. - - # otherwise I assume that you're just trying to release something - # that was already built and automatically uploaded. - - # let's publish amd64 to candidate channel and the channels below - snapcraft release riseup-vpn 20 candidate - snapcraft release riseup-vpn 20 beta - snapcraft release riseup-vpn 20 edge - - # and now the i386 build - snapcraft release riseup-vpn 19 candidate - snapcraft release riseup-vpn 19 beta - snapcraft release riseup-vpn 19 edge - -- cgit v1.2.3