You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@flink.apache.org by "alnzng (via GitHub)" <gi...@apache.org> on 2025/10/09 21:56:28 UTC

[PR] [Doc] Reorganize installation guide and simplify quickstart preparation sections [flink-agents]

alnzng opened a new pull request, #266:
URL: https://github.com/apache/flink-agents/pull/266

   <!--
   * Thank you very much for contributing to Flink Agents.
   * Please add the relevant components in the PR title. E.g., [api], [runtime], [java], [python], [hotfix], etc.
   -->
   
   <!-- Please link the PR to the relevant issue(s). Hotfix doesn't need this. -->
   Linked issue: #xxx
   
   ### Purpose of change
   
   <!-- What is the purpose of this change? -->
   Reorganize installation guide and simplify quickstart preparation sections
   
   ### Tests
   
   <!-- How is this change verified? -->
   deploy the doc locally
   
   ### API
   
   <!-- Does this change touches any public APIs? -->
   n/a
   
   ### Documentation
   
   <!-- Should this change be covered by the user documentation?-->
   n/a
   


-- 
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: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [Doc] Reorganize installation guide and simplify quickstart preparation sections [flink-agents]

Posted by "alnzng (via GitHub)" <gi...@apache.org>.
alnzng commented on code in PR #266:
URL: https://github.com/apache/flink-agents/pull/266#discussion_r2418444114


##########
docs/content/docs/get-started/installation.md:
##########
@@ -30,84 +30,185 @@ The sections below show how to install the required dependencies.
 {{< hint warning >}}
 __NOTE:__ To run on flink cluster, Flink-Agents requires flink version be a stable release of Flink 1.20.3.
 {{< /hint >}}
-## Install the Official Release
 
-#### Install Python Packages
+## Install Apache Flink
 
-{{< hint warning >}}
-__Note:__ This will be available after Flink Agents is released.
+Before installing Flink Agents, you need to have Apache Flink 1.20.3 installed.
+
+Download and extract Flink 1.20.3:
+
+```shell
+# Download Flink 1.20.3: https://www.apache.org/dyn/closer.lua/flink/flink-1.20.3/flink-1.20.3-bin-scala_2.12.tgz
+curl -LO https://archive.apache.org/dist/flink/flink-1.20.3/flink-1.20.3-bin-scala_2.12.tgz
+
+# Extract the archive
+tar -xzf flink-1.20.3-bin-scala_2.12.tgz
+
+# Set FLINK_HOME environment variable
+export FLINK_HOME=$(pwd)/flink-1.20.3
+
+# Copy the flink-python JAR from opt to lib (required for PyFlink)
+cp $FLINK_HOME/opt/flink-python-1.20.3.jar $FLINK_HOME/lib/
+```
+
+{{< hint info >}}
+**Note:** For more detailed Flink installation instructions, refer to the [Flink local installation guide](https://nightlies.apache.org/flink/flink-docs-release-1.20/docs/try-flink/local_installation/).
 {{< /hint >}}
 
-We recommand creating a Python virtual environment to install the Flink Agents Python library.
+## Install Flink Agents
+
+### Prerequisites
+
+* Python 3.10 or 3.11
+* For building from source, you also need:
+  - Unix-like environment (Linux, Mac OS X, Cygwin, or WSL)
+  - Git
+  - Maven 3
+  - Java 11
+
+### Set Up Python Environment (Recommended)
+
+We recommend using a Python virtual environment to isolate Flink Agents dependencies from your system Python packages.
 
-To install the latest Flink Agents release, run:
+**Create a virtual environment:**
 
+Using `venv` (built-in with Python 3):
 ```shell
-python -m pip install flink-agents
+# Create a virtual environment in a directory named 'venv'
+python3 -m venv venv
+
+# Activate the virtual environment
+# On Linux/macOS:
+source venv/bin/activate
+# On Windows:
+# venv\Scripts\activate
 ```
 
-#### Install Java Package
-To run java job on a Flink cluster, ensure the Flink Agents Java JARs are placed in the Flink lib directory:
+{{< hint info >}}
+**Note:** If `python3` command is not found, try `python` instead. Some systems alias `python` to Python 3.
+{{< /hint >}}
 
-<!-- TODO: fill in the command after Flink Agents is released -->
+**To deactivate when you're done:**
 ```shell
-# Download the Flink Agents released flink-agents-dist jar.
-
-# After downloading the bundle jar, copy it to Flink's lib directory.
-cp flink-agents-dist-$VERSION.jar $FLINK_HOME/lib/
+deactivate
 ```
 
+### Install Flink Agents Package
 
-## Build and Install from Source
+Choose one of the following installation methods:
 
-Prerequisites for building Flink Agents:
+#### From Official Release
 
-* Unix-like environment (we use Linux, Mac OS X, Cygwin, WSL)
-* Git
-* Maven
-* Java 11
-* Python 3.10 or 3.11
+{{< hint warning >}}
+__Note:__ This will be available after Flink Agents is released.
+{{< /hint >}}
 
-To clone from Git, run:
+Install Flink Agents using pip:
 
 ```shell
-git clone https://github.com/apache/flink-agents.git
+pip install flink-agents
 ```
 
-### Build
-To run on a Flink cluster, we need build the whole project.
+#### From Source
 
-We provide a script to run:
+**Clone the repository:**
 
 ```shell
+git clone https://github.com/apache/flink-agents.git

Review Comment:
   @xintongsong I agree with you that we should suggest the users to download a specific version of source code in each release/stable doc. However, this PR is merging into the main branch first, so in this doc we should suggest the users to use the latest codes due to the same consideration. 
   
   Next step I will create another PR(cherry-pick comment but with customization) which is dedicated for `release-0.1.0` branch, it will cover what you suggested here. 
   
   Let me know if this is not a right approach to make changes on release branch.



-- 
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: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [Doc] Reorganize installation guide and simplify quickstart preparation sections [flink-agents]

Posted by "wenjin272 (via GitHub)" <gi...@apache.org>.
wenjin272 commented on PR #266:
URL: https://github.com/apache/flink-agents/pull/266#issuecomment-3388010256

   Hi, @alnzng, thanks for your work. The changes look good to me.


-- 
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: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [Doc] Reorganize installation guide and simplify quickstart preparation sections [flink-agents]

Posted by "xintongsong (via GitHub)" <gi...@apache.org>.
xintongsong commented on code in PR #266:
URL: https://github.com/apache/flink-agents/pull/266#discussion_r2418546657


##########
docs/content/docs/get-started/installation.md:
##########
@@ -30,84 +30,185 @@ The sections below show how to install the required dependencies.
 {{< hint warning >}}
 __NOTE:__ To run on flink cluster, Flink-Agents requires flink version be a stable release of Flink 1.20.3.
 {{< /hint >}}
-## Install the Official Release
 
-#### Install Python Packages
+## Install Apache Flink
 
-{{< hint warning >}}
-__Note:__ This will be available after Flink Agents is released.
+Before installing Flink Agents, you need to have Apache Flink 1.20.3 installed.
+
+Download and extract Flink 1.20.3:
+
+```shell
+# Download Flink 1.20.3: https://www.apache.org/dyn/closer.lua/flink/flink-1.20.3/flink-1.20.3-bin-scala_2.12.tgz
+curl -LO https://archive.apache.org/dist/flink/flink-1.20.3/flink-1.20.3-bin-scala_2.12.tgz
+
+# Extract the archive
+tar -xzf flink-1.20.3-bin-scala_2.12.tgz
+
+# Set FLINK_HOME environment variable
+export FLINK_HOME=$(pwd)/flink-1.20.3
+
+# Copy the flink-python JAR from opt to lib (required for PyFlink)
+cp $FLINK_HOME/opt/flink-python-1.20.3.jar $FLINK_HOME/lib/
+```
+
+{{< hint info >}}
+**Note:** For more detailed Flink installation instructions, refer to the [Flink local installation guide](https://nightlies.apache.org/flink/flink-docs-release-1.20/docs/try-flink/local_installation/).
 {{< /hint >}}
 
-We recommand creating a Python virtual environment to install the Flink Agents Python library.
+## Install Flink Agents
+
+### Prerequisites
+
+* Python 3.10 or 3.11
+* For building from source, you also need:
+  - Unix-like environment (Linux, Mac OS X, Cygwin, or WSL)
+  - Git
+  - Maven 3
+  - Java 11
+
+### Set Up Python Environment (Recommended)
+
+We recommend using a Python virtual environment to isolate Flink Agents dependencies from your system Python packages.
 
-To install the latest Flink Agents release, run:
+**Create a virtual environment:**
 
+Using `venv` (built-in with Python 3):
 ```shell
-python -m pip install flink-agents
+# Create a virtual environment in a directory named 'venv'
+python3 -m venv venv
+
+# Activate the virtual environment
+# On Linux/macOS:
+source venv/bin/activate
+# On Windows:
+# venv\Scripts\activate
 ```
 
-#### Install Java Package
-To run java job on a Flink cluster, ensure the Flink Agents Java JARs are placed in the Flink lib directory:
+{{< hint info >}}
+**Note:** If `python3` command is not found, try `python` instead. Some systems alias `python` to Python 3.
+{{< /hint >}}
 
-<!-- TODO: fill in the command after Flink Agents is released -->
+**To deactivate when you're done:**
 ```shell
-# Download the Flink Agents released flink-agents-dist jar.
-
-# After downloading the bundle jar, copy it to Flink's lib directory.
-cp flink-agents-dist-$VERSION.jar $FLINK_HOME/lib/
+deactivate
 ```
 
+### Install Flink Agents Package
 
-## Build and Install from Source
+Choose one of the following installation methods:
 
-Prerequisites for building Flink Agents:
+#### From Official Release
 
-* Unix-like environment (we use Linux, Mac OS X, Cygwin, WSL)
-* Git
-* Maven
-* Java 11
-* Python 3.10 or 3.11
+{{< hint warning >}}
+__Note:__ This will be available after Flink Agents is released.
+{{< /hint >}}
 
-To clone from Git, run:
+Install Flink Agents using pip:
 
 ```shell
-git clone https://github.com/apache/flink-agents.git
+pip install flink-agents
 ```
 
-### Build
-To run on a Flink cluster, we need build the whole project.
+#### From Source
 
-We provide a script to run:
+**Clone the repository:**
 
 ```shell
+git clone https://github.com/apache/flink-agents.git

Review Comment:
   That approach makes perfect sense to me. I'll merge this PR as is.



-- 
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: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [Doc] Reorganize installation guide and simplify quickstart preparation sections [flink-agents]

Posted by "alnzng (via GitHub)" <gi...@apache.org>.
alnzng commented on PR #266:
URL: https://github.com/apache/flink-agents/pull/266#issuecomment-3387613495

   @xintongsong @wenjin272 Since we started the vote process, I want to validate the release through end-to-end testing (deploying quickstart jobs on a local Flink cluster), I found the installation documentation was not beginner-friendly. It assumes familiarity with Flink, PyFlink, and Python environments, making it difficult for newcomers to successfully deploy Flink Agents jobs.  (It did take me some time to run the quickstart examples sucessfully)
   
   I reorganized the documentation from a beginner's perspective so users can simply follow or copy-paste commands to run the examples successfully.
   
   Please help take a look and see if my proposed changes make sense.
   


-- 
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: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [Doc] Reorganize installation guide and simplify quickstart preparation sections [flink-agents]

Posted by "xintongsong (via GitHub)" <gi...@apache.org>.
xintongsong commented on code in PR #266:
URL: https://github.com/apache/flink-agents/pull/266#discussion_r2418309398


##########
docs/content/docs/get-started/installation.md:
##########
@@ -30,84 +30,185 @@ The sections below show how to install the required dependencies.
 {{< hint warning >}}
 __NOTE:__ To run on flink cluster, Flink-Agents requires flink version be a stable release of Flink 1.20.3.
 {{< /hint >}}
-## Install the Official Release
 
-#### Install Python Packages
+## Install Apache Flink
 
-{{< hint warning >}}
-__Note:__ This will be available after Flink Agents is released.
+Before installing Flink Agents, you need to have Apache Flink 1.20.3 installed.
+
+Download and extract Flink 1.20.3:
+
+```shell
+# Download Flink 1.20.3: https://www.apache.org/dyn/closer.lua/flink/flink-1.20.3/flink-1.20.3-bin-scala_2.12.tgz
+curl -LO https://archive.apache.org/dist/flink/flink-1.20.3/flink-1.20.3-bin-scala_2.12.tgz
+
+# Extract the archive
+tar -xzf flink-1.20.3-bin-scala_2.12.tgz
+
+# Set FLINK_HOME environment variable
+export FLINK_HOME=$(pwd)/flink-1.20.3
+
+# Copy the flink-python JAR from opt to lib (required for PyFlink)
+cp $FLINK_HOME/opt/flink-python-1.20.3.jar $FLINK_HOME/lib/
+```
+
+{{< hint info >}}
+**Note:** For more detailed Flink installation instructions, refer to the [Flink local installation guide](https://nightlies.apache.org/flink/flink-docs-release-1.20/docs/try-flink/local_installation/).
 {{< /hint >}}
 
-We recommand creating a Python virtual environment to install the Flink Agents Python library.
+## Install Flink Agents
+
+### Prerequisites
+
+* Python 3.10 or 3.11
+* For building from source, you also need:
+  - Unix-like environment (Linux, Mac OS X, Cygwin, or WSL)
+  - Git
+  - Maven 3
+  - Java 11
+
+### Set Up Python Environment (Recommended)
+
+We recommend using a Python virtual environment to isolate Flink Agents dependencies from your system Python packages.
 
-To install the latest Flink Agents release, run:
+**Create a virtual environment:**
 
+Using `venv` (built-in with Python 3):
 ```shell
-python -m pip install flink-agents
+# Create a virtual environment in a directory named 'venv'
+python3 -m venv venv
+
+# Activate the virtual environment
+# On Linux/macOS:
+source venv/bin/activate
+# On Windows:
+# venv\Scripts\activate
 ```
 
-#### Install Java Package
-To run java job on a Flink cluster, ensure the Flink Agents Java JARs are placed in the Flink lib directory:
+{{< hint info >}}
+**Note:** If `python3` command is not found, try `python` instead. Some systems alias `python` to Python 3.
+{{< /hint >}}
 
-<!-- TODO: fill in the command after Flink Agents is released -->
+**To deactivate when you're done:**
 ```shell
-# Download the Flink Agents released flink-agents-dist jar.
-
-# After downloading the bundle jar, copy it to Flink's lib directory.
-cp flink-agents-dist-$VERSION.jar $FLINK_HOME/lib/
+deactivate
 ```
 
+### Install Flink Agents Package
 
-## Build and Install from Source
+Choose one of the following installation methods:
 
-Prerequisites for building Flink Agents:
+#### From Official Release
 
-* Unix-like environment (we use Linux, Mac OS X, Cygwin, WSL)
-* Git
-* Maven
-* Java 11
-* Python 3.10 or 3.11
+{{< hint warning >}}
+__Note:__ This will be available after Flink Agents is released.
+{{< /hint >}}
 
-To clone from Git, run:
+Install Flink Agents using pip:
 
 ```shell
-git clone https://github.com/apache/flink-agents.git
+pip install flink-agents
 ```
 
-### Build
-To run on a Flink cluster, we need build the whole project.
+#### From Source
 
-We provide a script to run:
+**Clone the repository:**
 
 ```shell
+git clone https://github.com/apache/flink-agents.git

Review Comment:
   Nitpicking: We might want users to build the repo from the `release-0.1.0` tag (there will be one once formal released), rather than the latest main branch.
   
   And there are 2 ways of getting the codes:
   1. Clone the git repo
   2. Download from website. The expected download link is `https://www.apache.org/dyn/closer.lua/flink/flink-agents-0.1.0/flink-agents-0.1.0-src.tgz`, which should be available once formal released.



-- 
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: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org


Re: [PR] [Doc] Reorganize installation guide and simplify quickstart preparation sections [flink-agents]

Posted by "xintongsong (via GitHub)" <gi...@apache.org>.
xintongsong merged PR #266:
URL: https://github.com/apache/flink-agents/pull/266


-- 
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: issues-unsubscribe@flink.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org