Fast-track CLI installation

[toddjonker]

The only way to access the CLI today is by building from source.

We need at least one straightforward way to run the CLI, so we can streamline customer onboarding. This does not need to be a long-term solution, but I'd like to make incremental improvements to the first-contact experience, so newcomers can get up an running with a minimum of fuss.

Various documents will need updating once this is ready.

[rationull]

Is this aimed at a "first contact" experience with as few steps as possible, or at a longer term distribution mechanism for the CLI (such as publishing a jar on Maven and/or publishing a container image for the CLI?

[toddjonker]

Clarified the text; I'm suggesting we do whatever we can hack together to improve access to the CLI that's better than "build it from source". Does that make sense?

[rationull]

Yep, makes sense. I still wonder if codespaces would be a good place to start. I'll see if I can experiment with that sometime this week or weekend.

[rationull]

There are a few general classes of solutions here, as I see it:

In-browser playground

• Graal build targeting WASM, with a fully local browser-based CLI embedded in a static web page. This would be awesome. I have no idea how far we are from being able to build with Graal though. I think this is the best/most aspirational solution over all.
• Web frontend with lightweight/serverless sandboxed backend. I don't think we want to build or own this. A browser based solution is nice but adding backend cloud-based script execution is a whole thing.

Prebuilt binaries

• jars + scripts zipped together and uploaded as "releases" to GitHub. Hopefully the build artifacts could be extracted from CI builds, either automatically or manually from time to time. This is probably the easiest thing we can do. Requires local JRE to run.
• Published docker image. Probably the best user experience for downloading and running the CLI. Setting up an image build is easy, but this requires us to set up an account for publishing to the registry as well (ideally with image build and registry publish worked into CI automation). This actually might be pretty easy as well, thanks to Github Container Registry
• Package up for other package managers (e.g. homebrew). I think a docker approach would beat this in ease and flexibility.

From source

• Plain old build from source is disqualified by the premise of this issue.
• CodeSpaces/Dev Containers provide an in-browser instance of VS Code backed by a cloud-based containerized build environment with just a few clicks, provided the user is logged into Github and has storage and hours available including a reasonable free tier. Initial tests show this to be pretty slow (taking ~5 minutes to build a fresh container and build fusion-java) but there are optimizations to explore: dedicated limited build target, better base docker image, prebuilds if they are possible for our org account. This is interesting because it provides a dev environment, not just the CLI, but it is a very roundabout way to run the CLI.

My conclusions so far

I've looked at Codespaces a bit and it's interesting, but probably not a good solution unless we can get excited about the fact that it provides a dev environment too (maybe it's worth doing separately for that anyway). All things considered I think the Docker image solution (using GHCR) is probably the best combination of easy and functional and that's my inclination. Compared with other "binaries" options, Docker has the advantage of not requiring a local JRE and should work cleanly with Docker Desktop regardless of host OS.

However if we just want something immediate, we can manually upload a GitHub Release (presumably based on artifacts from CI results).

@toddjonker @SharkBaitDLS or anyone else: thoughts?

[toddjonker]

I agree with your take on in-browser experience. Probably worth pulling that into its own issue (or Discussion conversation?) where we can drop thoughts over time.

Regarding preconditions, I'd prefer a JDK requirement over a docker requirement any day. Personally, if I hit a site requiring docker to run the demo, I'd probably pass since that's just a heavyweight thing to install and manage. I'd rather deal with a JDK installation than a Docker/Finch install any day. Linux users are more likely to have it already, I'd guess. (Tho finch was pretty easy to get going on Mac, IIRC.)

gradle release already builds a distro, nominally an SDK since it includes the documentation tree alongside the CLI and jars. I think this is a reasonable incremental improvement to just offer a download of the SDK. It should also be easy-ish to have Gradle generate just the app.

I def like the idea of vending a Docker image, I just don't think its easier for the customer, or easier for us. Still, a reasonable (if not expected) thing to have.

Re Homebrew: personally I want this at some point. Ion's had their ion-cli there for some time, and its a snap to install and keep up to date. That said, that's built with Rust, and I'm not sure how well brew works for Java apps. FWIW my preferred JDK install is Corretto via Homebrew. Easy to keep multiple versions around and updated.

---

My suggestion is to start with the SDK download. First pass, we can get away with just recommending brew install corretto or whatever. Heck, we could have the fusion launch-script offer to install Java if one isn't around.

We can and should follow up with Docker, since that will be preferable to some audiences and use cases.

---

Re: the SDK download, yeah we could really hit the gas on it with a manual release. But I hope it's not hard to tie the CI artifacts to a fixed "latest" download link? There's a bit of version-labeling to work out there, but not too bad.

[rationull]

Funny, I'm the opposite -- Docker is my go-to for experimenting with new tools because of the isolation and ease of cleanup it provides (especially on Mac/Windows where Linux containers run in a VM). I actually just today had to redo my JDK install to test the build, because on this machine I was running openjdk from homebrew and for some reason our (declared JDK8 target) gradle build doesn't work with openjdk 23. Meanwhile Docker Desktop just keeps working, with dependencies isolated between containers.

If I were first encountering something like the Fusion CLI in the wild as a download, I would likely create a new Docker container (no Dockerfile, just with the CLI) based on an official OpenJDK or Corretto image, and pull it into there to run :)

---

For SDK download I'd prefer to stick with brew install corretto instructions -- having the launch script install a JDK seems too invasive to me.

(I would guess brew would work fine for Java apps, given the link to the JDK should be managed outside brew by JAVA_HOME regardless.) I can get separate issues cut for the other stuff before resolving this.

Looks like there are straightforward ways to create and update releases via the CLI and API which can both be hooked into Actions. So this seems like a reasonable place to start and I agree the SDK download is a more generally usable target.

Are you thinking a preview/latest release that gets updated with every build? Or nightlies?

[SharkBaitDLS]

I would also favor a Graal-based static webpage if we want to have a web option.

I'm not sure how well brew works for Java apps

Should be fine, conceptually brew is just a means to put files into an install location. As long as the cask includes the jar in the right place and then the actual fusion entry script ends up on the homebrew $PATH, I don't see why it wouldn't work.

As a hipster who prefers MacPorts over Homebrew, I'd also like to see it added there. I don't know as much about Homebrew, but at least with MacPorts you can model package dependencies so you can just state that it includes a JDK dependency.

[toddjonker]

@rationull I'm surprised that Gradle couldn't build the code with OpenJDK 23. It would expect it to run java --release 8 which is documented to work through at least 21.

Corretto shouldn't make a difference: it's just Amazon's build of the same code, with some minor additions.

Regardless, it shouldn't matter for running things, as long as Java 8 or later is on the path, or declared with JAVA_HOME, the Gradle-generated launch script should work.

FWIW I have a bunch of JDKs installed, never set JAVA_HOME, and things just work.

ls /Library/Java/JavaVirtualMachines/
amazon-corretto-11.jdk/  amazon-corretto-17.jdk/  amazon-corretto-21.jdk/ 
amazon-corretto-8.jdk/   jdk1.8.0_25.jdk/

I guess we should debug this a bit more.

[toddjonker]

Are you thinking a preview/latest release that gets updated with every build? Or nightlies?

At the moment, I think having a download link for the latest build is fine; that's what's going up to the docs site and it seems wise for those to be in sync.