Feature/update macos quickstart #1843

aofarrel · 2023-09-13T23:00:41Z

Description
Update Dockstore CLI install instructions, with an emphasis on updating the Mac OS instructions. Notably, we now correctly tell Mac users to use Java 17 instead of 11.

What's been tested

The Ubuntu instructions, because I only reformatted them, not changing any actual content
The "option B" instructions for Mac on an Intel-hardware Mac
Any new zsh alternatives to bash stuff

What has not been tested

The "option A" instructions for Mac, although I did fix the name of the file paths
The "option B" instructions for Mac on an Apple Silicon Mac -- this post from Ben implies option B might not work on Apple Silicon, but maybe the cask has been updated since then?

Specific feedback request
I listed some use cases for the Dockstore CLI after step 5, but I don't know if I "sold" it very well. Any thoughts?

Issues

Update Mac OS OpenJDK instructions #1814 -- old PR that got borked after a rebase 😬
Wrong commands to install openJDK dockstore#4486

Security
N/A

Please make sure that you've checked the following before submitting your pull request. Thanks!

As mentioned in the previous PR, since this is an external fork, these commits might need to be cherrypicked to an internal branch to get the tests to pass.

I've made sure this compiles, but I'm not sure how/if I can authenticate locally so I can see the onboarding page, so this is a bit of a blind change. 🙈 Would appreciate someone screenshotting the resulting markdown so I can ensure our flavor of markdown renders the ##### I've introduced distinctly from ####.

…aofarrel/dockstore-ui2 into feature/update-macos-quickstart

I tested the `brew` instructions on a fresh laptop that does not use Apple Silicon, but does use zsh. Docker 4.3.0 was chosen since that's the first version to support Apple Silicon.

Java and Docker dependencies are each now their own "part", and the two ways to install openJDK 17 have subheadings -- the combination of these two changes makes the Mac OS Java installation parts much less confusing. Additional zsh notice made on adding dockstore CLI to the path. Tell people their version of openJDK will vary. Give a few use cases for the Dockstore CLI after installing the required bits, and clarify WDL doesn't require any additional downloads. Remove some unnecessary numbering.

I tested the `brew` instructions on a fresh laptop that does not use Apple Silicon, but does use zsh. Docker 4.3.0 was chosen since that's the first version to support Apple Silicon.

Java and Docker dependencies are each now their own "part", and the two ways to install openJDK 17 have subheadings -- the combination of these two changes makes the Mac OS Java installation parts much less confusing. Additional zsh notice made on adding dockstore CLI to the path. Tell people their version of openJDK will vary. Give a few use cases for the Dockstore CLI after installing the required bits, and clarify WDL doesn't require any additional downloads. Remove some unnecessary numbering.

…aofarrel/dockstore-ui2 into feature/update-macos-quickstart

denis-yuen · 2023-09-14T14:11:06Z

Build issues are probably due to this being a fork (and then branch) rather than a branch inside the ui2 repo.
Overall though, probably need someone on Mac to review

denis-yuen

Pending Mac-saavy review

src/app/loginComponents/onboarding/downloadcliclient/downloadcliclient.component.ts

aofarrel · 2023-09-14T22:00:13Z

Most recent commit changes an additional file in attempt to fix the setup/set up issue in this UI element. Reviewer please ensure that element shows as "Set Up" since I can't view the onboarding page locally. (But it does compile!)

coverbeck · 2023-09-14T22:31:18Z

src/app/loginComponents/onboarding/downloadcliclient/downloadcliclient.component.ts

@@ -106,73 +109,88 @@ exec newgrp docker

 `;
    this.textDataMacOs = `
-#### Part 1a - Install Java dependencies
-We'll cover two ways to install Java 11.
+#### Part 1 - Install Java


Radical suggestion -- let's not get into into the details of how to install Java, and just have links.

Your steps are very detailed, and yet:

I didn't install Java on my Mac either of the ways you list; I installed was from https://adoptium.net/, which at the time was the only Apple Silicon native JDK implementation.

The minor version you have, 17.0.2, is old (the 2 part), I think. While you could update it to the latest, it could probably become quickly out of date.

There are different ways of switching JVM versions on a Mac -- I use jenv, and I don't think we want to be too prescriptive about how to do it.

Instructions change with newer releases.

I think it's better not to get too detailed and let the package owners tell you how to install.

What do you think?

There is a caveat... if we tell people to use homebrew, they have to install xCode command line tools, and that can take time. If we tell people to use OpenJDK from the archival website, they will be told on said website "hey, this is old software, don't use this!" and will end up with an older version than what homebrew would give them.

That being said: I ultimately agree with this point, and would rather direct people to just use homebrew. Installing homebrew is user-friendly, and iirc it handles the (sometimes iffy) xcode cl tools installation well. People who are developing bioinformatics tools often have it already.

Action items:

Does homebrew-OpenJDK work on Apple Silicon? This comment implies it might not (or at least at the time did not).

How long does the version of xcode that homebrew actually take to install on modern (2018-onwards-ish, intel + Apple Silicon) Macs? At what point would it be slow enough to use to say "hey, this could be slow," or does homebrew warn about this for us?

I stick by my suggestion that we just not get into how to install Java. :) I wouldn't even recommend homebrew in our doc.

To clarify, I'm not anti-Homebrew; I have it installed (on a Silicon Mac, FWIW) and use it, although I don't happen to use it to install Java. But I don't think it's Dockstore's domain to take a position on how to configure your local machine.

Could you cover this change?

re-bumping, I can't assess this

coverbeck · 2023-09-14T22:32:53Z

src/app/loginComponents/onboarding/onboarding.component.html

@@ -75,7 +75,7 @@ <h5>Dockstore External Services</h5>
    <button mat-raised-button matStepperPrevious class="pull-right mt-2"><mat-icon>navigate_before</mat-icon>Back</button>
  </mat-step>
  <mat-step>
-    <ng-template matStepLabel>Setup Dockstore CLI</ng-template>
+    <ng-template matStepLabel>Set Up Dockstore CLI</ng-template>


Good catch.

svonworl · 2023-09-15T02:54:29Z

src/app/loginComponents/onboarding/downloadcliclient/downloadcliclient.component.ts

 ------------------------------
-Set up our Dockstore CLI application in order to test workflows from the command line for [local development](${Dockstore.DOCUMENTATION_URL}/launch-with/launch.html#dockstore-cli), [validate .dockstore.yml files](${Dockstore.DOCUMENTATION_URL}/advanced-topics/dockstore-cli/yaml-command-line-validator-tool.html) for registering tools and workflows,
+You can search for workflows or launch them with our cloud partners using the Dockstore website, but we also provide a command-line tool to make developing and launching workflows more convenient. Set up our Dockstore CLI application in order to test workflows from the command line for [local development](${Dockstore.DOCUMENTATION_URL}/launch-with/launch.html#dockstore-cli), [validate .dockstore.yml files](${Dockstore.DOCUMENTATION_URL}/advanced-topics/dockstore-cli/yaml-command-line-validator-tool.html) for registering tools and workflows,


I like this new text, it's clear and to the point and communicates the basic concepts in a way that new users can understand.

aofarrel · 2023-09-20T21:15:49Z

More notes about Apple Silicon compatibility:

As I see it, the problem isn’t with miniwdl (or cromwell) but with running a WDL that uses x86 containers on an ARM mac. Where miniwdl or cromwell comes into play is in how the WDL runtime loads the docker container that your WDL needs to run. Given that ARM macs can run x86 executables via software emulation, there should be a way to make docker (and then miniwdl/cromwell) run x86 containers on ARM macs. Or if you had docker containers that support ARM natively, that would also work.
-- Phil Shapiro, OpenWDL Slack, r/e chanzuckerberg/miniwdl#652

Other notes from that discussion:

Try using Docker parameter --platform=linux/amd64
Try setting an env variable: export DOCKER_DEFAULT_PLATFORM=linux/amd64
The actual Cromwell JAR works on Apple Silicon, and miniwdl likely does to (troublesome Docker images notwithstanding)

denis-yuen · 2024-03-11T17:59:38Z

Checking in on this as part of https://ucsc-cgl.atlassian.net/browse/SEAB-6003
@coverbeck or @svonworl can someone mac-based take over this and get it over the line?

aofarrel · 2024-03-12T00:55:22Z

Although I'm using a different machine now, I'm still using Intel hardware, so I can't test the Apple Silicon stuff. Recommend whichever reviewer has Apple Silicon hardware checks that a workflow running an x86 Docker image actually goes through.

See also:

I haven't seen issues running x86 Docker images from people running Linux on other ARM architecture; I think this is mostly a Mac issue.

Also worth keeping in mind that although the heavy hitters of Docker Hub tend to build multi-arch images, most bioinformatics Dockers images seem to be solely available in x86.

coverbeck · 2024-03-12T16:52:23Z

src/app/loginComponents/onboarding/downloadcliclient/downloadcliclient.component.ts

@@ -106,73 +109,88 @@ exec newgrp docker

 `;
    this.textDataMacOs = `
-#### Part 1a - Install Java dependencies
-We'll cover two ways to install Java 11.
+#### Part 1 - Install Java


I stick by my suggestion that we just not get into how to install Java. :) I wouldn't even recommend homebrew in our doc.

To clarify, I'm not anti-Homebrew; I have it installed (on a Silicon Mac, FWIW) and use it, although I don't happen to use it to install Java. But I don't think it's Dockstore's domain to take a position on how to configure your local machine.

denis-yuen · 2024-03-26T15:00:23Z

src/app/loginComponents/onboarding/downloadcliclient/downloadcliclient.component.ts

@@ -106,73 +109,88 @@ exec newgrp docker

 `;
    this.textDataMacOs = `
-#### Part 1a - Install Java dependencies
-We'll cover two ways to install Java 11.
+#### Part 1 - Install Java


re-bumping, I can't assess this

coverbeck · 2024-04-12T23:15:43Z

Closing in favor of #1964, which is based off of this, but whose branch is in this repo which allows somebody other than Ash to respond to PR comments.

aofarrel added 8 commits July 12, 2023 14:22

Update Mac OS instructions

fabca14

Update Mac OS instructions

f3f4972

Merge branch 'feature/update-macos-quickstart' of https://github.com/…

22350fa

…aofarrel/dockstore-ui2 into feature/update-macos-quickstart

Bare minimum update (brew version tested by me)

2a78e05

I tested the `brew` instructions on a fresh laptop that does not use Apple Silicon, but does use zsh. Docker 4.3.0 was chosen since that's the first version to support Apple Silicon.

Bare minimum update (brew version tested by me)

94e529c

I tested the `brew` instructions on a fresh laptop that does not use Apple Silicon, but does use zsh. Docker 4.3.0 was chosen since that's the first version to support Apple Silicon.

Merge branch 'feature/update-macos-quickstart' of https://github.com/…

649bfe3

…aofarrel/dockstore-ui2 into feature/update-macos-quickstart

denis-yuen requested review from coverbeck and bvizzier-ucsc September 14, 2023 14:09

denis-yuen requested a review from svonworl September 14, 2023 14:11

denis-yuen assigned bvizzier-ucsc Sep 14, 2023

denis-yuen reviewed Sep 14, 2023

View reviewed changes

src/app/loginComponents/onboarding/downloadcliclient/downloadcliclient.component.ts Outdated Show resolved Hide resolved

rm "dependencies", fix "setup", clarify CLI is optional

e47a422

coverbeck reviewed Sep 14, 2023

View reviewed changes

svonworl approved these changes Sep 15, 2023

View reviewed changes

aofarrel marked this pull request as ready for review September 15, 2023 23:53

denis-yuen requested review from coverbeck, svonworl and denis-yuen March 11, 2024 17:58

coverbeck approved these changes Mar 12, 2024

View reviewed changes

svonworl approved these changes Mar 12, 2024

View reviewed changes

denis-yuen assigned coverbeck and unassigned bvizzier-ucsc Mar 12, 2024

denis-yuen approved these changes Mar 26, 2024

View reviewed changes

coverbeck mentioned this pull request Apr 12, 2024

Update Mac OS Quickstart #1964

Merged

11 tasks

coverbeck closed this Apr 12, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Feature/update macos quickstart #1843

Feature/update macos quickstart #1843

aofarrel commented Sep 13, 2023 •

edited

Loading

denis-yuen commented Sep 14, 2023

denis-yuen left a comment

aofarrel commented Sep 14, 2023

coverbeck Sep 14, 2023

aofarrel Sep 14, 2023 •

edited

Loading

coverbeck Mar 12, 2024

denis-yuen Mar 12, 2024

denis-yuen Mar 26, 2024

coverbeck Sep 14, 2023

svonworl Sep 15, 2023

aofarrel commented Sep 20, 2023

denis-yuen commented Mar 11, 2024

aofarrel commented Mar 12, 2024

coverbeck Mar 12, 2024

denis-yuen Mar 26, 2024

coverbeck commented Apr 12, 2024

Feature/update macos quickstart #1843

Feature/update macos quickstart #1843

Conversation

aofarrel commented Sep 13, 2023 • edited Loading

denis-yuen commented Sep 14, 2023

denis-yuen left a comment

Choose a reason for hiding this comment

aofarrel commented Sep 14, 2023

Choose a reason for hiding this comment

aofarrel Sep 14, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aofarrel commented Sep 20, 2023

denis-yuen commented Mar 11, 2024

aofarrel commented Mar 12, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

coverbeck commented Apr 12, 2024

aofarrel commented Sep 13, 2023 •

edited

Loading

aofarrel Sep 14, 2023 •

edited

Loading