janniklinde commented on code in PR #2388: URL: https://github.com/apache/systemds/pull/2388#discussion_r2630301129
########## docs/site/release_install.md: ########## @@ -0,0 +1,122 @@ + +# Install SystemDS from a Release + +This guide explains how to install and set up SystemDS using the pre-built release archives. + +--- + +- [1. Download a Release](#1-download-a-release) +- [2. Install on Windows](#2-install-on-windows) +- [3. Install on Ubuntu 22.04](#3-install-on-ubuntu-2204) +- [4. Install on macOS](#4-install-pon-macos) +- [5. Verify the Installation](#5-verify-the-installation) + +--- + +# 1. Download a Release + +Download the official release archive from the Apache SystemDS website: + +https://apache.org/dyn/closer.lua/systemds/ Review Comment: Maybe rather point to https://systemds.apache.org/download ########## docs/site/run_extended.md: ########## @@ -0,0 +1,253 @@ +# Running SystemDS + +This guide explains how to run SystemDS regardless of whether you installed it from a Release or built it from Source. All execution modes -local, Spark, and federated- are covered in this document. + +--- + +- [1. Prerequisites](#1-prerequisites) +- [2. Set SYSTEMDS_ROOT and PATH](#2-set-systemds_root-and-path) +- [3. Run a Simple Script Locally](#3-run-a-simple-script-locally) +- [4. Run a Script on Spark](#4-run-a-script-on-spark) +- [5. Run a Script in Federated Mode](#5-run-a-script-in-federated-mode) + +--- + +# 1. Prerequisites + +### Java Requirement ### +For compatability with Spark execution and parser components, **Java 17** is strongly recommended for SystemDS. + +Verify Java version: + +```bash +java -version +``` + +### Spark (required only for Spark execution) ### + +- Use Spark 3.x. +- Spark 4.x is not supported due to ANTLR runtime incompatibilities. + +Verify Spark version: + +```bash +spark-submit --version +``` + +--- + +# 2. Set SYSTEMDS_ROOT and PATH + +This step is required for both Release and Source-build installations. Run the following in the root directory of your SystemDS installation: + +```bash +export SYSTEMDS_ROOT=$(pwd) +export PATH="$SYSTEMDS_ROOT/bin:$PATH" +``` + +It can be beneficial to enter these into your `~/.profile` or `~/.bashrc` for linux, +(but remember to change `$(pwd` to the full folder path) +or your environment variables in windows to enable reuse between terminals and restarts. + +```bash +echo 'export SYSTEMDS_ROOT='$(pwd) >> ~/.bashrc +echo 'export PATH=$SYSTEMDS_ROOT/bin:$PATH' >> ~/.bashrc +``` Review Comment: I would mention that in `release_install` as well. Otherwise, after restarting the terminal people might get confused when only following quickstart. Also, for prerequisites that are already mentioned in the install guides can be referenced rather than repeating the same thing. ########## docs/site/release_install.md: ########## @@ -0,0 +1,122 @@ + +# Install SystemDS from a Release + +This guide explains how to install and set up SystemDS using the pre-built release archives. + +--- + +- [1. Download a Release](#1-download-a-release) +- [2. Install on Windows](#2-install-on-windows) +- [3. Install on Ubuntu 22.04](#3-install-on-ubuntu-2204) +- [4. Install on macOS](#4-install-pon-macos) +- [5. Verify the Installation](#5-verify-the-installation) + +--- + +# 1. Download a Release + +Download the official release archive from the Apache SystemDS website: + +https://apache.org/dyn/closer.lua/systemds/ + +After downloading the file `systemds-<VERSION>.tar.gz`, place the file in any directory you choose for installation. + +### Java Requirement ### +For compatability with Spark execution and parser components, **Java 17** is strongly recommended for SystemDS. + +Verify Java 17: + +```bash +java -version +``` + +If missing, install a JDK 17 distribution. + +--- + +# 2. Install on Windows + +### 2.1 Extract the Release Archive + +Use Windows built-in extractor. + +### 2.2 Set Evironment Variables + +To run SystemDS from the command line, configure: +- `SYSTEMDS_ROOT`-> the extracted folder +- Add `%SYSTEMDS_ROOT%\bin` to your `PATH` + +Example (PowerShell): + +```bash +setx SYSTEMDS_ROOT "C:\path\to\systemds-<VERSION>" +setx PATH "$env:SYSTEMDS_ROOT\bin;$env:PATH" +``` + +Restart the terminal afterward. + +# 3. Install on Ubuntu 22.04 + +### 3.1 Extract the Release + +```bash +cd /path/to/install +tar -xvf systemds-<VERSION>.tar.gz +cd systemds-<VERSION> +``` + +### 3.2 Add SystemDS to PATH + +```bash +export SYSTEMDS_ROOT=$(pwd) +export PATH="$SYSTEMDS_ROOT/bin:$PATH" +``` Review Comment: I tried to follow the guide for ubuntu 22.04 (I set up a fresh docker image with java, tar and wget installed). After downloading and extracting the release, I got stuck with this error. Docker image I tested on: ```dockerfile FROM ubuntu:22.04 ENV DEBIAN_FRONTEND=noninteractive RUN apt-get update && \ apt-get install -y \ openjdk-17-jdk \ ca-certificates \ wget \ && apt-get clean \ && rm -rf /var/lib/apt/lists/* WORKDIR /opt RUN wget https://dlcdn.apache.org/systemds/3.3.0/systemds-3.3.0-bin.tgz && \ tar -xzf systemds-3.3.0-bin.tgz && \ rm systemds-3.3.0-bin.tgz CMD ["bash"] ``` ``` root@9385e1a25ddd:/opt# ls systemds-3.3.0-bin root@9385e1a25ddd:/opt# cd systemds-3.3.0-bin root@9385e1a25ddd:/opt/systemds-3.3.0-bin# java -version openjdk version "17.0.17" 2025-10-21 OpenJDK Runtime Environment (build 17.0.17+10-Ubuntu-122.04) OpenJDK 64-Bit Server VM (build 17.0.17+10-Ubuntu-122.04, mixed mode, sharing) root@9385e1a25ddd:/opt/systemds-3.3.0-bin# export SYSTEMDS_ROOT=$(pwd) root@9385e1a25ddd:/opt/systemds-3.3.0-bin# export PATH="$SYSTEMDS_ROOT/bin:$PATH" root@9385e1a25ddd:/opt/systemds-3.3.0-bin# systemds -help Help requested. Will exit after extended usage message! Usage: /opt/systemds-3.3.0-bin/bin/systemds [-r] [SystemDS.jar] [-f] <dml-filename> [arguments] [-help] SystemDS.jar : Specify a custom SystemDS.jar file (this will be prepended to the classpath or fed to spark-submit -r : Spawn a debug server for remote debugging (standalone and spark driver only atm). Default port is 8787 - change within this script if necessary. See SystemDS documentation on how to attach a remote debugger. -f : Optional prefix to the dml-filename for consistency with previous behavior dml-filename : The script file to run. This is mandatory unless running as a federated worker (see below). arguments : The arguments specified after the DML script are passed to SystemDS. Specify parameters that need to go to java/spark-submit by editing this run script. -help : Print this usage message and SystemDS parameter info Worker Usage: /opt/systemds-3.3.0-bin/bin/systemds [-r] WORKER [SystemDS.jar] <portnumber> [arguments] [-help] port : The port to open for the federated worker. Federated Monitoring Usage: /opt/systemds-3.3.0-bin/bin/systemds [-r] FEDMONITORING [SystemDS.jar] <portnumber> [arguments] [-help] port : The port to open for the federated monitoring tool. Set custom launch configuration by setting/editing SYSTEMDS_STANDALONE_OPTS and/or SYSTEMDS_DISTRIBUTED_OPTS. Set the environment variable SYSDS_DISTRIBUTED=1 to run spark-submit instead of local java Set SYSDS_QUIET=1 to omit extra information printed by this run script. ---------------------------------------------------------------------- Further help on SystemDS arguments: Error: Unable to access jarfile org.apache.sysds.api.DMLScript root@9385e1a25ddd:/opt/systemds-3.3.0-bin# cd .. root@9385e1a25ddd:/opt# echo 'print("Hello World!")' > hello.dml root@9385e1a25ddd:/opt# systemds -f hello.dml ############################################################################### # SYSTEMDS_ROOT= /opt/systemds-3.3.0-bin # SYSTEMDS_JAR_FILE= # SYSDS_EXEC_MODE= singlenode # CONFIG_FILE= -config /opt/systemds-3.3.0-bin/conf/SystemDS-config.xml # LOG4JPROP= -Dlog4j.configuration=file:/opt/systemds-3.3.0-bin/conf/log4j.properties # HADOOP_HOME= /opt/systemds-3.3.0-bin/lib/hadoop # # Running script hello.dml locally with opts: # Executing command: java -Xmx4g -Xms4g -Xmn400m -Dlog4j.configuration=file:/opt/systemds-3.3.0-bin/conf/log4j.properties -jar -f hello.dml -exec singlenode -config /opt/systemds-3.3.0-bin/conf/SystemDS-config.xml ############################################################################### Error: Invalid or corrupt jarfile hello.dml ``` ########## docs/site/source_install.md: ########## Review Comment: Would be nice to mention that you can also add the `bin` folder to `PATH`. Then you can directly access your last local build through CLI. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
