adding java install and upgrade page (#1539)

* adding java install options Signed-off-by: Matt Nelson <[email protected]> * update links Signed-off-by: Matt Nelson <[email protected]> * adding message on non-brew install Signed-off-by: Matt Nelson <[email protected]> * edit content Signed-off-by: Alexandra Tran <[email protected]> --------- Signed-off-by: Matt Nelson <[email protected]> Signed-off-by: Alexandra Tran <[email protected]> Co-authored-by: Alexandra Tran <[email protected]> Co-authored-by: Alexandra Tran Carrillo <[email protected]>
hyperledger · Mar 26, 2024 · d16dc9d · d16dc9d
1 parent 8c11b5b
commit d16dc9d
Show file tree

Hide file tree

Showing 10 changed files with 216 additions and 89 deletions.
diff --git a/docs/private-networks/how-to/index.md b/docs/private-networks/how-to/index.md
@@ -25,10 +25,11 @@ The following features are shared with [public networks](../../public-networks/i
   - [Configure ports](../../public-networks/how-to/connect/configure-ports.md)
   - [Manage peers](../../public-networks/how-to/connect/manage-peers.md)
   - [Specify NAT method](../../public-networks/how-to/connect/specify-nat.md)
-- [Configure the Java Virtual Machine](../../public-networks/how-to/configure-jvm/index.md)
-  - [Pass JVM options](../../public-networks/how-to/configure-jvm/pass-jvm-options.md)
-  - [Manage JVM memory](../../public-networks/how-to/configure-jvm/manage-memory.md)
-  - [Use Java Flight Recorder](../../public-networks/how-to/configure-jvm/java-flight-recorder.md)
+- Configure Java:
+  - [Install and update Java](../../public-networks/how-to/configure-java/install-update-java.md)
+  - [Pass JVM options](../../public-networks/how-to/configure-java/pass-jvm-options.md)
+  - [Manage JVM memory](../../public-networks/how-to/configure-java/manage-memory.md)
+  - [Use Java Flight Recorder](../../public-networks/how-to/configure-java/java-flight-recorder.md)
 - Develop dapps:
   - [Use Hardhat](../../public-networks/how-to/develop/hardhat.md)
   - [Use client libraries](../../public-networks/how-to/develop/client-libraries.md)

diff --git a/docs/public-networks/get-started/system-requirements.md b/docs/public-networks/get-started/system-requirements.md
@@ -22,7 +22,7 @@ CPU requirements are highest when syncing to the network and typically reduce af
 ## Java distribution and installation
 
 Besu requires an installation of Java 17+ to run.
-We currently recommend two Java distributions, [OpenJDK 17](https://jdk.java.net/17/) and
+We currently recommend two Java distributions, [OpenJDK 21](https://jdk.java.net/21/) and
 [OpenJ9](https://www.eclipse.org/openj9/), though you can experiment based on your needs.
 
 OpenJDK is the default for many Java users and is balanced in performance and garbage collection.
@@ -46,95 +46,85 @@ docker image, or install the OpenJ9 JDK using the following steps:
     ```
 2. Uncompress the binaries:
 
-<Tabs>
-
-   <TabItem value="Command" label="Command" default>
-
-   ```bash
-   tar -xvf YOUR_J9_IMAGE.tar.gz
-   ```
-   </TabItem>
+    <Tabs>
+    <TabItem value="Command" label="Command" default>
 
-  <TabItem value="Example" label="Example">
-
-   ```bash
-   tar -xvf ibm-semeru-open-jdk_x64_linux_17.0.5_8_openj9-0.35.0.tar.gz
-   ```
+    ```bash
+    tar -xvf YOUR_J9_IMAGE.tar.gz
+    ```
 
-   </TabItem>
+    </TabItem>
+    <TabItem value="Example" label="Example">
+
+    ```bash 
+    tar -xvf ibm-semeru-open-jdk_x64_linux_17.0.5_8_openj9-0.35.0.tar.gz
+    ```
 
-</Tabs>
+    </TabItem>
+    </Tabs>
 
 3. Move the binaries to `bin` directory:
 
-<Tabs>
-
-   <TabItem value="Command" label="Command" default>
-
-   ```bash
-   sudo cp -r YOUR_IMAGE/ /usr/bin/
-   ```
-   </TabItem>
-
-  <TabItem value="Example" label="Example">
-
-   ```bash
-   sudo cp -r jdk-17.0.5+8/ /usr/bin/
-   ```
-
-   </TabItem>
+    <Tabs>
+    <TabItem value="Command" label="Command" default>
 
-</Tabs>
+    ```bash
+    sudo cp -r YOUR_IMAGE/ /usr/bin/
+    ```
 
-4. Specify OpenJ9 for Java on your machine:
+    </TabItem>
+    <TabItem value="Example" label="Example">
 
-<Tabs>
-
-   <TabItem value="Command" label="Command" default>
+    ```bash
+    sudo cp -r jdk-17.0.5+8/ /usr/bin/
+    ```
 
-   ```bash
-   sudo update-alternatives --install "/usr/bin/java" "java" "/usr/bin/YOUR_IMAGE" 1
-   sudo update-alternatives --config java (and choose OpenJ9)
-   ```
+    </TabItem>
+    </Tabs>
 
-   </TabItem>
+4. Specify OpenJ9 for Java on your machine:
 
-  <TabItem value="Example" label="Example">
+    <Tabs>
+    <TabItem value="Command" label="Command" default>
 
-   ```bash
-   sudo update-alternatives --install "/usr/bin/java" "java" "/usr/bin/jdk-17.0.5+8/bin/java"
-   ```
+    ```bash
+    sudo update-alternatives --install "/usr/bin/java" "java" "/usr/bin/YOUR_IMAGE" 1
+    sudo update-alternatives --config java (and choose OpenJ9)
+    ```
 
-   </TabItem>
+    </TabItem>
+    <TabItem value="Example" label="Example">
 
-</Tabs>
+    ```bash
+    sudo update-alternatives --install "/usr/bin/java" "java" "/usr/bin/jdk-17.0.5+8/bin/java"
+    ```
 
-   Change your `JAVA_HOME` to OpenJ9 (if using the JDK implementation), where `jdk-install-dir` is
-   the installation location you specified:
-
-<Tabs>
+    </TabItem>
+    </Tabs>
 
-   <TabItem value="Command" label="Command" default>
+    Change your `JAVA_HOME` to OpenJ9 (if using the JDK implementation), where `jdk-install-dir` is
+    the installation location you specified:
 
-   ```bash
-   export JAVA_HOME=jdk-install-dir`
-   ```
+    <Tabs>
+    <TabItem value="Command" label="Command" default>
 
-   </TabItem>
+    ```bash
+    export JAVA_HOME=jdk-install-dir`
+    ```
 
-  <TabItem value="Example" label="Example">
+    </TabItem>
+    <TabItem value="Example" label="Example">
 
-   ```bash
-   export JAVA_HOME=/usr/bin/jdk-17.0.5+8
-   ```
+    ```bash
+    export JAVA_HOME=/usr/bin/jdk-17.0.5+8
+    ```
 
-   </TabItem>
-
-</Tabs>
+    </TabItem>
+    </Tabs>
 
 ## Java Virtual Machine size
 
-For Mainnet and testnets, the minimum [Java Virtual Machine (JVM) memory requirement is 8 GB](../how-to/configure-jvm/manage-memory.md).
+For Mainnet and testnets, the minimum [Java Virtual Machine (JVM) memory requirement is 8 GB](../how-to/configure-java/manage-memory.md).
 
 JVM memory requirements are highest when syncing, but will reduce after the node is synchronized to the chain head. Monitor your system to determine your actual JVM memory needs.
 

diff --git a/docs/public-networks/how-to/configure-java/_category_.json b/docs/public-networks/how-to/configure-java/_category_.json
@@ -0,0 +1,4 @@
+{
+  "label": "Configure Java",
+  "position": 8
+}
diff --git a/docs/public-networks/how-to/configure-java/install-update-java.md b/docs/public-networks/how-to/configure-java/install-update-java.md
@@ -0,0 +1,148 @@
+---
+sidebar_position: 1
+description: Install or update Java for use with Hyperledger Besu
+tags:
+  - public networks
+  - private networks
+---
+
+# Install and update Java
+
+There are many flavors of Java and the Java Virtual Machine (JVM) that work with Besu.
+They might impact performance, start time, and more.
+Consider the options carefully when installing Java on your host machine.
+Currently, [we recommend Java 21](../../get-started/system-requirements.md#java-distribution-and-installation).
+
+## Install Java
+
+Download the version of Java you would like to install.
+If you are running Besu outside a virtual environment, like Docker, you must have Java installed on
+the host machine.
+
+:::tip
+Download [OpenJDK 21](https://jdk.java.net/21/).
+:::
+
+You can find platform-specific installation instructions with the download.
+The following installation examples use OpenJDK.
+
+### Install Java on Ubuntu
+
+You can install OpenJDK on Ubuntu using the `apt-get` command.
+
+1. Ensure `apt` libraries are installed and up-to-date:
+
+    ```bash
+    sudo apt update && sudo apt upgrade -y
+    ```
+
+2. Confirm whether Java is already installed:
+
+    ```bash
+    java -version
+    ```
+
+    If a version is returned, and you would like to update, see how to [update Java on Ubuntu](#update-java-on-ubuntu).
+
+3. If no version is returned, use `apt` to install the preferred version. 
+
+    ```bash
+    sudo apt-get install openjdk-21-jdk
+    ```
+
+4. Confirm the installation:
+
+    ```bash
+    java -version
+    ```
+
+5. You might need to update your environment to make Java visible to Besu.
+    Edit the `.bashrc` file in your home directory (or create it if needed) and add the following
+    lines to the end of the file:
+
+    ```text title=".bashrc"
+    export JAVA_HOME=$(dirname $(dirname $(readlink -f $(which java))))
+    export PATH=$PATH:$JAVA_HOME/bin
+    ```
+
+6. Save your changes and source the file:
+
+    ```bash
+    source ~/.bashrc 
+    ```
+
+7. Verify that you updated your environment:
+
+    ```bash
+    echo $JAVA_HOME
+    echo $PATH
+    ```
+
+    You should see the JDK versions output.
+
+### Install Java on MacOS 
+
+You can install OpenJDK on MacOS using Homebrew.
+
+1. With `brew` installed, run:
+
+    ```bash
+    brew install openjdk@21
+    ```
+
+    You can target another version if you prefer. 
+
+2. Confirm the installation:
+
+    ```bash
+    java -version
+    ```
+
+    The OpenJDK version you install should display.
+
+    If this command returns `command not found: java`, check your terminal logs.
+    Brew might prompt you to create a symlink or update your path variables within the logs in the
+    terminal output.
+    If so, run the prompts provided.
+
+## Update Java 
+
+### Update Java on Ubuntu
+
+To update Java on Ubuntu, uninstall the current versions and follow the instructions to
+[install Java on Ubuntu](#install-java-on-ubuntu) with your target version.
+
+If you started with this guide, you can uninstall Java using the following command:
+
+```bash
+sudo apt-get purge openjdk-\*
+```
+
+### Update Java on MacOS
+
+You can update Java on MacOS using Homebrew.
+
+1. List your Homebrew packages:
+
+    ```bash
+    brew ls
+    ```
+
+2. To update the JDK version (for example, from 17 to 21), uninstall the old version and reinstall
+    the target version:
+
+    ```bash
+    brew uninstall openjdk@17
+    brew install openjdk@21
+    ```
+
+    :::note
+    If you installed a version of Java not using Homebrew, it is located at
+    `/Library/Java/JavaVirtualMachines` and can be safely deleted from that directory.
+    :::
+
+3. To update point versions of Java, run the `upgrade` command:
+
+    ```bash
+    brew upgrade openjdk
+    ```
diff --git a/...-to/configure-jvm/java-flight-recorder.md → ...to/configure-java/java-flight-recorder.md b/...-to/configure-jvm/java-flight-recorder.md → ...to/configure-java/java-flight-recorder.md
@@ -1,6 +1,6 @@
 ---
 title: Use Java Flight Recorder
-sidebar_position: 3
+sidebar_position: 4
 description: Using Java Flight Recorder with Hyperledger Besu
 tags:
   - public networks

diff --git a/...rks/how-to/configure-jvm/manage-memory.md → ...ks/how-to/configure-java/manage-memory.md b/...rks/how-to/configure-jvm/manage-memory.md → ...ks/how-to/configure-java/manage-memory.md
@@ -1,6 +1,6 @@
 ---
 title: Manage JVM memory
-sidebar_position: 2
+sidebar_position: 3
 description: Besu memory management
 tags:
   - public networks

diff --git a/.../how-to/configure-jvm/pass-jvm-options.md → ...how-to/configure-java/pass-jvm-options.md b/.../how-to/configure-jvm/pass-jvm-options.md → ...how-to/configure-java/pass-jvm-options.md
@@ -1,6 +1,6 @@
 ---
 title: Pass JVM options
-sidebar_position: 1
+sidebar_position: 2
 description: Passing Java virtual machine JVM options to Hyperledger Besu at runtime
 tags:
   - public networks

diff --git a/docs/public-networks/how-to/configure-jvm/_category_.json b/docs/public-networks/how-to/configure-jvm/_category_.json
diff --git a/docs/public-networks/how-to/configure-jvm/index.md b/docs/public-networks/how-to/configure-jvm/index.md
diff --git a/docs/public-networks/how-to/troubleshoot/performance.md b/docs/public-networks/how-to/troubleshoot/performance.md
@@ -24,7 +24,7 @@ try the following suggestions:
 * Configure memory and RAM:
   * If you have RAM constraints, use [OpenJ9](../../get-started/system-requirements.md) if you're
     running on `x86_64` Linux architecture to reduce memory usage.
-  * Review and change your [Java heap size](../configure-jvm/manage-memory.md) if necessary.
+  * Review and change your [Java heap size](../configure-java/manage-memory.md) if necessary.
     5GB is an appropriate limit.
     Higher values may improve sync time, but can be reduced after completing sync.
   * Ensure Besu is using [jemalloc](../../get-started/install/binary-distribution.md).