Docs: Add extended quickstart and installation guides (release + source) by yiseungmi87 · Pull Request #2388 · apache/systemds

yiseungmi87 · 2025-12-18T02:20:45Z

This PR introduces improved documentation for new users of SystemDS:

Added

quickstart_extended.md - Overview page linking installation and execution docs
release_install.md - Clean, updated installation guide for release users
source_install.md - Updated guide for building SystemDS from source
run_extended.md - Comprehensive execution guide (local, Spark, federated)
run.md- Slightly modified

Scope

Documentation-only changes
No changes to SystemDS code or runtime behavior
Existing run.md is intentionally left for compatibility

Purpose

These changes provide clearer onboarding for new SystemDS users and consolidate documentation into a consistent structure.

Let me know if adjustments are desired before merging.

janniklinde

Thank you @yiseungmi87 for the good first PR, it seems to be quite clear and understandable so far.

I did not manage to set up SystemDS for Ubuntu by only following your guide (which should be the goal of the install guide) so please have a look into that. You can use a clean docker image to follow your guide and identify possible points of failure. Similarly, please check that for the other operating systems no such weak points exist (if you have windows, maybe try the setup on a new user). Also, I realized that when cloning SystemDS source code via GitHub Desktop on Windows, it might get stuck in the cloning process so we should provide a solution for that (e.g. use 'git' CLI for cloning rather than the app). So far, I have not tested the install for Windows / macOS but will do so once my current comments are resolved.

docs/site/release_install.md

docs/site/run_extended.md

docs/site/source_install.md

yiseungmi87 · 2025-12-29T02:54:23Z

Thanks again for the detailed feedback @janniklinde !

In addition to the changes in this PR, I verified the guides end-to-end on clean OS environments (Windows, Ubuntu, Mac).
Following only the Quickstart and installation guides, I was able to successfully complete the setup from installation through running the basic Hello World example on all tested systems.

Also, I’ve addressed the remaining minor issues such as markdown rendering issue or duplicate explanations.

Happy to adjust further if anything is still unclear or fails in your setup.

janniklinde

Thank you for the improvements @yiseungmi87. I left you some more feedback on where you could further refine the quickstart guide

docs/site/release_install.md

docs/site/source_install.md

docs/site/run_extended.md

yiseungmi87 · 2026-01-19T12:43:25Z

Hi, thanks a lot for the feedback! @janniklinde

I’ve updated the PR to reflect all points mentioned so far.

Regarding the note that this file feels like a clone of docs/site/install.md: that makes sense. The changes here are mainly meant as clarifications and fixes to the existing install guide, not as a separate alternative. So, what I understood is that the right next step would be to apply these changes directly to install.md and drop the separate file.

Before doing that, I just wanted to double-check that this approach is what you meant.

Thanks again!

janniklinde

Thanks again for your contribution @yiseungmi87 and sorry for the late response. The install instructions now seem to work. I noticed that your references are sometimes inconsistent (sometimes you refer to the html and sometimes to md).

Please replace the existing files (install.md and run.md) and double check the links/references. Also, the old run.md contains instructions for using Intel MKL native instructions. Is there a specific reason you left that out?

Finally, for this guide to be accessible as html, we require the header (like in the old install.md). When these issues are addressed, I think we are ready to merge.

docs/site/run_extended.md

docs/site/source_install.md

yiseungmi87 · 2026-01-27T10:40:21Z

Thanks for the feedback!
I’ve now merged the extended guides into the existing install.md and run.md.
All links and references were updated accordingly.
Please let me know if anything still looks off.

janniklinde

Thank you for the updates and overall contribution @yiseungmi87, with this PR your DIA project is successfully completed. I left some minor notes for us to fix before merging. We will take it from here.

janniklinde · 2026-01-30T08:31:54Z

docs/site/release_install.md

+(Optional but recommended) To make SystemDS available in new terminals, add the following lines to your shell configuration (e.g., ~/.bashrc or ~/.profile):
+```bash
+export SYSTEMDS_ROOT=/absolute/path/to/systemds-<VERSION>
+export SYSTEMDS_JAR_FILE=$(find "$SYSTEMDS_ROOT" -maxdepth 1 -type f -name "systemds-*.jar" | head -n 1)


Putting this line into .bashrc or .profile is usually bad practice because this command then runs every time you start a new terminal. Putting a path like /absolute/path/to/systemds-<VERSION>-bin/systemds-<VERSION>.jar would be preferred.

janniklinde · 2026-01-30T08:39:07Z

docs/site/release_install.md

+Hello World!
+```
+
+On some Ubuntu setups (including clean Docker images), running SystemDS directly may fail with `Invalid or corrupt jarfile hello.dml` Error. Ensuring that `SYSTEMDS_JAR_FILE`points to the SystemDS JAR shipped with the release resolves this issue.


Can be removed because the manual explicitly states to set SYSTEMDS_JAR_FILE -> redundant

janniklinde · 2026-01-30T08:41:19Z

docs/site/quickstart_extended.md

+
+If you simply want to *use* SystemDS without modifying the source code, the recommended approach is to install SystemDS from an official Apache release.
+
+**Full Release Installation Guide:** [SystemDS Install from release](https://apache.github.io/systemds/site/release_install.html)


Name like title of release_install.

janniklinde · 2026-01-30T08:41:59Z

docs/site/quickstart_extended.md

+
+If you plan to contribute to SystemDS or need to modify its internals, you can build SystemDS from source.
+
+**Full Source Build Guide:** [SystemDS Install from source](https://apache.github.io/systemds/site/source_install.html)


Name like title from source_install and update reference because it's now called install.md

Baunsgaard · 2026-02-12T17:05:55Z

docs/site/install.md

-At the time of writing the commands to install R 4.0.2 are:
+R can be installed using the CRAN repository.
+
+**Ubuntu 22.04** 


Baunsgaard

few comments, but LGTM.

Would be good with explicit tests for the docs.

Consider adding them as python tests inside /src/main/python

The tests should parse the docs, extract script parts, and run.

Baunsgaard · 2026-02-12T17:06:17Z

docs/site/install.md

+**Ubuntu 22.04** 

 ```bash
 sudo apt install dirmngr gnupg apt-transport-https ca-certificates software-properties-common
 sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys E298A3A825C0D65DFD57CBB651716619E084DAB9
 sudo add-apt-repository 'deb https://cloud.r-project.org/bin/linux/ubuntu focal-cran40/'
+sudo apt update
 sudo apt install r-base
 ```

-Optionally, you need to install the R dependencies for integration tests, like this:
-(use `sudo` mode if the script couldn't write to local R library)
+**Ubuntu 22.04**


Both say 22.04, one should be the old.

Baunsgaard · 2026-02-12T17:07:01Z

docs/site/install.md

+Setup your environment variables with JAVA_HOME and MAVEN_HOME. Using these variables add the JAVA_HOME/bin and MAVEN_HOME/bin to the path environment variable. An example of setting it for Java can be found here: <https://www.thewindowsclub.com/set-java_home-in-windows-10>

-To run the system we also have to setup some Hadoop and spark specific libraries. These can be found in the SystemDS repository. To add this, simply take out the files, or add 'src/test/config/hadoop_bin_windows/bin' to PATH. Just like for JAVA_HOME set a HADOOP_HOME to the environment variable without the bin part, and add the %HADOOP_HOME%/bin to path.
+To run the system we also have to setup some Hadoop and Spark specific libraries. These can be found in the SystemDS repository. To add this, simply take out the files, or add 'src/test/config/hadoop_bin_windows/bin' to PATH. Just like for JAVA_HOME set a HADOOP_HOME to the environment variable without the bin part, and add the `%HADOOP_HOME%\bin` to path.


use / not \

Baunsgaard · 2026-02-12T17:09:02Z

docs/site/install.md

+# 6. Next Steps

-To execute dml scripts look at [Execute SystemDS](run), this step is not needed to develop in systemds, but it helps setting up the command-line execution of systemds.
+Now everything is setup and ready to go! For running scripts in Spark mode or experimenting with federated workers, see the Execution Guide: [Execute SystemDS](run.html)


not completely sure, but i think we can simply link to run not run.html

Docs: extended quickstart and install/run improvements

4843d2f

github-project-automation bot added this to SystemDS PR Queue Dec 18, 2025

github-project-automation bot moved this to In Progress in SystemDS PR Queue Dec 18, 2025

janniklinde reviewed Dec 18, 2025

View reviewed changes

docs/site/release_install.md Outdated Show resolved Hide resolved

docs/site/release_install.md Show resolved Hide resolved

docs/site/run_extended.md Outdated Show resolved Hide resolved

docs/site/source_install.md Outdated Show resolved Hide resolved

docs: adress os-specific install issues and further changes

c72c6bd

janniklinde reviewed Dec 29, 2025

View reviewed changes

docs: remove redundant and fix CLI usage and JAR resolution

9bcd1c0

janniklinde reviewed Jan 26, 2026

View reviewed changes

docs/site/run_extended.md Outdated Show resolved Hide resolved

docs/site/source_install.md Outdated Show resolved Hide resolved

docs: merge extended guides into existing install and run docs

c0bcf58

janniklinde reviewed Jan 30, 2026

View reviewed changes

Baunsgaard reviewed Feb 12, 2026

View reviewed changes


		If you simply want to use SystemDS without modifying the source code, the recommended approach is to install SystemDS from an official Apache release.

		Full Release Installation Guide: [SystemDS Install from release](https://apache.github.io/systemds/site/release_install.html)


		If you plan to contribute to SystemDS or need to modify its internals, you can build SystemDS from source.

		Full Source Build Guide: [SystemDS Install from source](https://apache.github.io/systemds/site/source_install.html)

Conversation

yiseungmi87 commented Dec 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Added

Scope

Purpose

Uh oh!

janniklinde left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yiseungmi87 commented Dec 29, 2025

Uh oh!

janniklinde left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

yiseungmi87 commented Jan 19, 2026

Uh oh!

janniklinde left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

yiseungmi87 commented Jan 27, 2026

Uh oh!

janniklinde left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Baunsgaard left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

yiseungmi87 commented Dec 18, 2025 •

edited

Loading