This is an automated email from the ASF dual-hosted git repository. tzulitai pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/flink-statefun.git
The following commit(s) were added to refs/heads/master by this push: new 732adb2 [hotfix] Update README.md 732adb2 is described below commit 732adb2bdb5f480c9e022393ecfd0df04966b41d Author: Tzu-Li (Gordon) Tai <tzuli...@apache.org> AuthorDate: Tue Apr 13 15:29:08 2021 +0800 [hotfix] Update README.md Updates the README for the following: - Make "Getting Started" up-to-date to point to the playground examples. - Fix the "Building the Project" section to actually refer to how to the build the project itself. --- README.md | 144 +++++++++++++++++--------------------------------------------- 1 file changed, 38 insertions(+), 106 deletions(-) diff --git a/README.md b/README.md index 0fabab8..89cf345 100755 --- a/README.md +++ b/README.md @@ -28,13 +28,11 @@ For code examples, please take a look at the [examples](statefun-examples/). * [Function modules and extensibility](#modules) * [Runtime](#runtime) - [Getting Started](#getting-started) - * [Running a full example](#greeter) - * [Project setup](#project-setup) - * [Building the Project](#build) - * [Running in the IDE](#ide-harness) -- [Deploying Applications](#deploying) - * [Deploying with a Docker image](#docker) - * [Deploying as a Flink job](#flink) + * [New Java Users](#java) + * [New Python Users](#python) +- [Building the Project](#build) + * [Prerequisites](#build-prerequisites) + * [Procedures](#build-procedures) - [Contributing](#contributing) - [License](#license) @@ -114,125 +112,59 @@ This makes it possible to execute functions on a Kubernetes deployment, a FaaS p ## <a name="getting-started"></a>Getting Started -Follow the steps here to get started right away with Stateful Functions. +We highly recommend starting from the the tutorials and examples that can be found in the [Stateful Functions Playground repository](https://github.com/apache/flink-statefun-playground). There you will find material that serve as a great starting point if you've just started with getting to know the project, or looking for specific examples of common usage patterns. -This guide will walk you through setting up to -start developing and testing your own Stateful Functions (Java) application, and running an existing example. If you prefer to get started with Python, have a look into the [StateFun Python SDK](https://github.com/apache/flink-statefun/tree/master/statefun-sdk-python) and the [Python Greeter example](https://github.com/apache/flink-statefun-playground/tree/dev/python/greeter). +### <a name="java">New Java Users -### <a name="project-setup"></a>Project Setup - -Prerequisites: - -* Docker - -* Maven 3.5.x or above - -* Java 8 or above - -You can quickly get started building Stateful Functions applications using the provided quickstart Maven archetype: +Head over to the [Java SDK Showcase](https://github.com/apache/flink-statefun-playground/tree/release-3.0/java/showcase), or the [Java Greeter Example](https://github.com/apache/flink-statefun-playground/tree/release-3.0/java/greeter) in the playground repository. +Alternatively, execute the following commands to clone the playground repository locally: ``` -mvn archetype:generate \ - -DarchetypeGroupId=org.apache.flink \ - -DarchetypeArtifactId=statefun-quickstart \ - -DarchetypeVersion=3.1-SNAPSHOT +$ git clone -b release-3.0 https://github.com/apache/flink-statefun-playground.git +$ cd java/showcase # or, java/greeter ``` -This allows you to name your newly created project. It will interactively ask you for the `GroupId`, -`ArtifactId` and package name. There will be a new directory with the same name as your `ArtifactId`. - -We recommend you import this project into your IDE to develop and test it. -IntelliJ IDEA supports Maven projects out of the box. If you use Eclipse, the `m2e` plugin allows to import -Maven projects. Some Eclipse bundles include that plugin by default, others require you to install it manually. - -### <a name="build"></a>Building the Project - -If you want to build/package your project, go to your project directory and run the `mvn clean package` command. You will find a JAR file that contains your application, plus any libraries that you may have added as dependencies to the application: `target/<artifact-id>-<version>.jar`. - -### <a name="ide-harness"></a>Running from the IDE +### <a name="python">New Python Users -To test out your application, you can directly run it in the IDE without any further packaging or deployments. - -Please see the [Harness example](statefun-examples/statefun-flink-harness-example) on how to do that. - -### <a name="greeter"></a>Running a full example - -As a simple demonstration, we will be going through the steps to run the [Greeter example](https://github.com/apache/flink-statefun-playground/tree/dev/java/greeter). - -Before anything else, make sure that you have locally [built the project as well as the base Stateful Functions Docker image](#build). -Then, follow the next steps to run the example: +For new Python users, head over to the [Python SDK Showcase](https://github.com/apache/flink-statefun-playground/tree/release-3.0/python/showcase), or the [Python Greeter Example](https://github.com/apache/flink-statefun-playground/tree/release-3.0/python/greeter) in the playground repository. +Alternatively, execute the following commands to clone the playground repository locally: ``` -cd statefun-examples/statefun-greeter-example -docker-compose build -docker-compose up +$ git clone -b release-3.0 https://github.com/apache/flink-statefun-playground.git +$ cd python/showcase # or, python/greeter ``` -This example contains a very basic stateful function with a Kafka ingress and a Kafka egress. +Each tutorial or example in the playground repository will have a `README` that contains details on building and running the code. Take a look and try it out yourself! -To see the example in action, send some messages to the topic `names`, and see what comes out out of the topic `greetings`: +## <a name="build"></a>Building the Project -``` -docker-compose exec kafka-broker kafka-console-producer.sh \ - --broker-list localhost:9092 \ - --topic names -``` +This section contains information for building this project. -``` -docker-compose exec kafka-broker kafka-console-consumer.sh \ - --bootstrap-server localhost:9092 \ - --isolation-level read_committed \ - --from-beginning \ - --topic greetings -``` +### <a name="build-prerequisites">Prerequisites -## <a name="deploying"></a>Deploying Applications +- Maven v3.5+ +- Java 8 +- Docker v20.10+ (if you'd like to run the end-to-end tests as part of the build) -Stateful Functions applications can be packaged as either [standalone applications](https://ci.apache.org/projects/flink/flink-statefun-docs-master/deployment-and-operations/packaging.html#images) or [Flink jobs](https://ci.apache.org/projects/flink/flink-statefun-docs-master/deployment-and-operations/packaging.html#flink-jar) that can be -submitted to a Flink cluster. +### <a name="build-procedures">Procedures -### <a name="docker"></a>Deploying with a Docker image - -Below is an example Dockerfile for building a Stateful Functions image with an [embedded](https://ci.apache.org/projects/flink/flink-statefun-docs-master/sdk/modules.html#embedded-module) module (Java) for an application called `statefun-example`. - -``` -FROM flink-statefun[:version-tag] - -RUN mkdir -p /opt/statefun/modules/statefun-example - -COPY target/statefun-example*jar /opt/statefun/modules/statefun-example/ -``` - -### <a name="flink"></a>Deploying as a Flink job - -If you prefer to package your Stateful Functions application as a Flink job to submit to an existing Flink cluster, -simply include `statefun-flink-distribution` as a dependency to your application. - -``` -<dependency> - <groupId>org.apache.flink</groupId> - <artifactId>statefun-flink-distribution</artifactId> - <version>3.1-SNAPSHOT</version> -</dependency> -``` - -It includes all the runtime dependencies and configures the application's main entry-point. -You do not need to take any action beyond adding the dependency to your POM file. - -<div class="alert alert-info"> - <strong>Attention:</strong> The distribution must be bundled in your application fat JAR so that it is on Flink's <a href="https://ci.apache.org/projects/flink/flink-docs-stable/monitoring/debugging_classloading.html#inverted-class-loading-and-classloader-resolution-order">user code class loader</a> -</div> - -``` -{$FLINK_DIR}/bin/flink run ./statefun-example.jar -``` +1. Build source code: + ``` + $ mvn clean install + $ # or, alternatively, run the end-to-end tests as well (requires Docker) + $ mvn clean install -Prun-e2e-tests + ``` -## <a name="contributing"></a>Contributing +2. Build Stateful Functions Docker image: This step requires that you've already compiled artifacts from the source code. + ``` + $ ./tools/docker/build-distribution.sh + ``` + This builds a local Docker image tagged as `flink-statefun:<version_of_current_source_version>`. -There are multiple ways to enhance the Stateful Functions API for different types of applications; the runtime and operations will also evolve with the developments in Apache Flink. +## <a name="code-of-conduct"></a>Code of Conduct -You can learn more about how to contribute in the [Apache Flink website](https://flink.apache.org/contributing/how-to-contribute.html). For code contributions, please read carefully the [Contributing Code](https://flink.apache.org/contributing/contribute-code.html) section and check the _Stateful Functions_ component in [Jira](https://issues.apache.org/jira/browse/FLINK-15969?jql=project%20%3D%20FLINK%20AND%20component%20%3D%20%22Stateful%20Functions%22) for an overview of ongoing commun [...] +Apache Flink, Stateful Functions, and all its associated repositories follow the [Code of Conduct of the Apache Software Foundation](https://www.apache.org/foundation/policies/conduct). ## <a name="license"></a>License -The code in this repository is licensed under the [Apache Software License 2](LICENSE). +The code in this repository is licensed under the [Apache Software License 2.0](LICENSE).