Update the Spring developer guide #4301
Conversation
Improved the guide to align with the upcoming release of Camunda 8 Desktop Modeler and C8 Run. Includes revising the Prerequisites section, removing redundant steps now covered by the new Self-managed setup, and improving the clarity and structure of the getting started steps.
camundom
added
hold
|
👋 🤖 ✅ Looks like the changes were ported across versions, nice job! 🎉 You can read more about the versioning within our docs in our documentation guidelines. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
| [comment]: SmPrereqs/ | ||
|
|
||
| ## Step 1: Install Camunda 8 Self-Managed | ||
| ## Prerequisites | ||
|
|
||
| <Install/> | ||
| Before getting started, ensure you have the following in your local environment: | ||
|
|
||
| ## Step 2: Create a new Spring Boot project | ||
| - Access to your preferred code editor or IDE | ||
| - [OpenJDK 21+](https://jdk.java.net/) | ||
| - [Camunda 8 Desktop Modeler](https://camunda.com/download/modeler/) and [Camunda 8 Server<br/>](https://camunda.com/download/modeler/)_If you've already signed up for a Self-managed account, you can find the download links in your welcome email._ |
There was a problem hiding this comment.
blocking, in one way or another:
Previous to this, we've been creating a separate prerequisites sub-document for each different form of installation. I can get on-board with eliminating the sub-documents, especially if this is the final form of this guide. But if this isn't the final expected form of this guide, we should stick with that approach.
If we do stick with this approach of pulling this section inline instead of importing from a sub-document, then there are a couple things we should clean up:
- The
[comment]: SmPrereqs/line -- it's unclear to me why we would preserve that path as a "comment". - The now-unused import lines at the top of this file:
import SmPrereqs from './react-components/sm-prerequisites.md' import Install from './react-components/install-plain-java.md' - (maybe) The unused sub-documents in the
react-componentsfolder.
There was a problem hiding this comment.
Thanks for taking a look and sharing your feedback @pepopowitz !
This would be the final form of this guide. Would it be good to add these steps to the separate prerequisites sub-document instead, replacing the older format of installing SM? AFAIK, there are two other guides that use prerequisites and the sub-document would help the other guides as well.
The [comment]: SmPrereqs/ line -- it's unclear to me why we would preserve that path as a "comment".
This is temporary. If we go ahead with using the sub-document, then this line would get uncommented.
The now-unused import lines at the top of this file:
These would be removed as well.
PS: This is my first contribution towards docs where I've edited/written using markdown and understanding the structure was new to me :)
There was a problem hiding this comment.
Ah, I didn't realize there was reuse across guides -- we should definitely update in the sub-documents instead.
Thank you!!!
There was a problem hiding this comment.
There is a component for reusing the C8Run installation content created already, but I haven't yet dropped it into existing pages like this. I would recommend using a separate component than the ones that already exist for the Java install, though, as I am not sure each page is ready to use with C8Run.
|
FYI @conceptualshark |
|
|
||
| ## Step 2: Create a new Spring Boot project | ||
| - Access to your preferred code editor or IDE | ||
| - [OpenJDK 21+](https://jdk.java.net/) |
There was a problem hiding this comment.
Do we want to be opinionated about this link? I opted against including a specific link/recommendation in the C8Run documentation, as each user may have a different preference for install (and using the java-provided install is More Annoying in some cases).
There was a problem hiding this comment.
I want to be more opinionated, but my first concern is this is the wrong link to OpenJDK. We want something like https://openjdk.org/install/
There was a problem hiding this comment.
The idea in providing a direct link was to make it easier for users to quickly access the right resource—the same link OpenJDK provides on their installation page. We also received user feedback requesting direct links for easier access. The link to https://openjdk.org/install/ works fine as well.
There was a problem hiding this comment.
I don't really love the OpenJDK install page - I think it's a little misleading/confusing, and OpenJDK offers no follow-up on setting JAVA_HOME when installed in this way.
Using homebrew or apt-get for mac and linux installs is going to be a lot more straightforward, but this opens us up to needing to document multiple paths of entry because OpenJDK's documentation isn't terribly robust. I just want to make sure that being opinionated doesn't actually get us fielding more questions than it answers.
There was a problem hiding this comment.
Either way, a note to make sure JAVA_HOME is set correctly would probably help; that way, no matter the installation, that check happens before they continue.
| ## Step 2: Create a new Spring Boot project | ||
| - Access to your preferred code editor or IDE | ||
| - [OpenJDK 21+](https://jdk.java.net/) | ||
| - [Camunda 8 Desktop Modeler](https://camunda.com/download/modeler/) and [Camunda 8 Server<br/>](https://camunda.com/download/modeler/)_If you've already signed up for a Self-Managed account, you can find the download links in your welcome email._ |
There was a problem hiding this comment.
I'm unsure of the timeline for this PR, so some of these questions depend on if it's meant to go live before or after the upcoming marketing website changes to support SM/C8Run:
-
We're using using the name Camunda 8 Run currently; should we use that name here for now, and update it if it's changed to "Camunda 8 Server"?
-
While the marketing pages are still in development, we can link to the docs at https://docs.camunda.io/docs/next/self-managed/setup/deploy/local/c8run/
-
Should the email download line be removed until that new flow is enabled?
There was a problem hiding this comment.
The name will be Camunda 8 Run. After our meeting today, @melanie-butcher will communicate this to the respective teams.
@camundom, is your timeline for this PR aligned with the 8.6? Or just the marketing pages/assets being ready too?
There was a problem hiding this comment.
@akeller, thanks for the update! Yes, the timeline for this PR is 8.6. The marketing pages are ready for preview and undergoing testing, while the download email is WIP.
|
After the prj-dev-gettingstarted meeting today, I made the following changes:
|
…clude-the-new-installation-of-self-managed
|
@akeller What led to removing the non-production notice? Is that something we'd need to repeat in other guides? |
- Removed links to unused components - Added note to ensure JAVA_Home is set properly - Changed OpenJDK install url
|
@camundom Is this still waiting for marketing/email journey updates? Is there a version of this update we can deliver for 8.6? |
| <Install/> | ||
| - Access to your preferred code editor or IDE | ||
| - [OpenJDK 21+](https://openjdk.org/install/) | ||
| - [Camunda 8 Desktop Modeler](https://camunda.com/download/modeler/) and [Camunda 8 Run<br/>](https://camunda.com/download/modeler/)_If you've already signed up for a Self-Managed account, you can find the download links in your welcome email._ |
There was a problem hiding this comment.
I noticed that C8Run is linked to the modeller link.
Could we add a link to C8Run installation page?
I would not expect users to wait for email or look for email when they are already committed to trying out this guide.
Plus, we do not get the download link in our email. It is not as easy as downloading an app. it needs a few more steps.
There was a problem hiding this comment.
It looks like the download emailer hasn't gone up yet. I'll add the link to the C8 Page.
|
Removing |
…clude-the-new-installation-of-self-managed
|
I resolved the merge conflicts that may not be in the spirit of this PR, but I wanted to get the |
|
@camundom is this ready to merge? It will need to be backported to appear in the 8.6 docs, but it's something DevEx can help with. Just let us know. |
|
I will backport and merge this now. |
…clude-the-new-installation-of-self-managed
| <Install/> | ||
| - Access to your preferred code editor or IDE | ||
| - [OpenJDK 21+](https://openjdk.org/install/) | ||
| - Camunda 8 Desktop Modeler and Camunda 8 Run |
There was a problem hiding this comment.
Can we link to the docs for both here?
There was a problem hiding this comment.
I will incorporate this in a separate PR @conceptualshark 👍
christinaausley
deleted the
4300-update-the-spring-developer-guide-to-include-the-new-installation-of-self-managed
branch
|
🧹 Preview environment for this PR has been torn down. |
|
The preview environment relating to the commit f95a9cb has successfully been deployed. You can access it at https://preview.docs.camunda.cloud/pr-4301/index.html |
Description
Improved the guide to align with the upcoming release of Camunda 8 Desktop Modeler and C8 Run. This includes revising the Prerequisites section, removing redundant steps now covered by the new Self-managed setup, and improving the clarity and structure of the steps for getting started.
What's changed?
Prerequisites
Discarded Step 1: Install Camunda 8 Self-managed
Steps 2 & 3
When should this change go live?
holdlabel or convert to draft PR)PR Checklist
/versioned_docsdirectory./docsdirectory (aka/next/).