Reintroduce Quickstart Image by polyzos · Pull Request #3150 · apache/fluss

polyzos · 2026-04-21T07:50:47Z

No description provided.

polyzos · 2026-04-21T08:37:49Z

Copilot

Pull request overview

This PR reintroduces and operationalizes a pre-bundled Flink quickstart Docker image (apache/fluss-quickstart-flink) and updates the website/docs to reference it via a version placeholder, with CI support to publish images for main and release tags.

Changes:

Add a new quickstartFlinkDockerVersion field to website version metadata and expose it via the remark version-replacement plugin.
Update quickstart/observability/security docs to reference the new quickstart image tag placeholder.
Introduce a docker/quickstart-flink Dockerfile and a GitHub Actions workflow to build/push apache/fluss and apache/fluss-quickstart-flink.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
website/src/plugins/remark-version-replace/index.js	Adds $FLUSS_QUICKSTART_FLINK_DOCKER_VERSION$ replacement for docs.
website/fluss-versions.json	Updates docker versioning for `next` and adds quickstart image version metadata.
website/docs/quickstart/security.md	Switches Flink image references to the quickstart image placeholder and adjusts SQL client invocation.
website/docs/quickstart/flink.md	Simplifies the Flink quickstart by using the pre-bundled quickstart image.
website/docs/maintenance/observability/quickstart.md	Switches Flink image references to the quickstart image placeholder.
website/community/how-to-release/creating-a-fluss-release.mdx	Updates release steps to reflect CI-built `apache/fluss` and manual RC quickstart image build.
docker/quickstart-flink/Dockerfile	New Dockerfile to build the pre-bundled Flink quickstart image.
.github/workflows/docker.yaml	New workflow to build/push Docker images on `main` and `v*` tags (skipping RC quickstart builds).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-21T12:09:43Z

+    "dockerVersion": "latest-snapshot",
+    "quickstartFlinkDockerVersion": "2.2-latest-snapshot",
    "paimonVersion": "1.3.1",
    "paimonVersionShort": "1.3",


The next entry is a *-SNAPSHOT version, but it still relies on the plugin’s default mavenRepoUrl (Maven Central). Docs like website/docs/quickstart/lakehouse.md use $FLUSS_MAVEN_REPO_URL$ to download Fluss artifacts, and Maven Central won’t have snapshots—those downloads will fail for next. Add an explicit mavenRepoUrl for next pointing at the ASF snapshots repository (or wherever Fluss snapshots are published).

Suggested change

"paimonVersionShort": "1.3",

"paimonVersionShort": "1.3",

"mavenRepoUrl": "https://repository.apache.org/content/repositories/snapshots",

Copilot · 2026-04-21T12:09:43Z

+    image: apache/fluss-quickstart-flink:$FLUSS_QUICKSTART_FLINK_DOCKER_VERSION$
    depends_on:
      - jobmanager
+    command: sql-client


The sql-client service uses command: sql-client, but the quickstart image Dockerfile doesn’t add a sql-client executable/script—only Flink’s bin/sql-client.sh exists. This will likely make docker compose run sql-client fail. Update the service command to invoke Flink’s SQL client script explicitly (or add a wrapper executable in the image).

Suggested change

command: sql-client

command: /opt/flink/bin/sql-client.sh

Copilot · 2026-04-21T12:09:44Z

            "$FLUSS_VERSION_SHORT$": version.shortVersion,
            "$FLUSS_DOCKER_VERSION$": version.dockerVersion,
+            "$FLUSS_QUICKSTART_FLINK_DOCKER_VERSION$": version.quickstartFlinkDockerVersion || `2.2-${version.dockerVersion}`,
            "$PAIMON_VERSION$": version.paimonVersion,


The default fallback hardcodes the Flink major/minor (2.2) in the replacement logic. This duplicates the same value in website/fluss-versions.json and .github/workflows/docker.yaml, increasing the chance the docs and image tags drift when the recommended Flink version changes. Prefer making quickstartFlinkDockerVersion required in fluss-versions.json (and removing the fallback), or at least centralize the 2.2 value in one place used by the plugin.

Copilot · 2026-04-21T12:09:44Z

+  # The Flink version bundled in the quickstart image. Update this when the
+  # recommended Flink version for the quickstart changes.


QUICKSTART_FLINK_VERSION is another hardcoded source of truth for the Flink version prefix used in apache/fluss-quickstart-flink tags. Since the website replacement logic also hardcodes 2.2 as a fallback and fluss-versions.json now contains quickstartFlinkDockerVersion, these can easily get out of sync. Consider deriving this env var from website/fluss-versions.json (e.g., parse the next entry’s quickstartFlinkDockerVersion) or documenting that all three places must be updated together.

Suggested change

# The Flink version bundled in the quickstart image. Update this when the

# recommended Flink version for the quickstart changes.

# The Flink version prefix bundled in the quickstart image.

# Keep this in sync with:

# - website/fluss-versions.json (`quickstartFlinkDockerVersion`, typically in `next`)

# - the website replacement logic fallback for the quickstart Flink version

# Update all of them together when the recommended quickstart Flink version changes.

Copilot · 2026-04-21T12:09:44Z

+ARG FLINK_VERSION=2.2
+ARG FLUSS_VERSION
+ARG FLUSS_MAVEN_REPO_URL=https://repo1.maven.org/maven2
+
+# Pre-install dependencies into Flink lib so that quickstart users do not need to
+# download any jars manually:
+#   - Fluss Flink connector
+#   - Fluss S3 filesystem plugin (needed for remote tiered storage in quickstart)
+#   - Flink Faker connector (for generating demo data in quickstart examples)
+#   - Flink Prometheus metrics reporter (placed in lib/ so it is on the classpath;
+#     it acts as a reporter only when explicitly configured via metrics.reporter.*)
+RUN set -ex; \
+    # Fluss JARs are downloaded from the official Apache Maven repository (Maven Central
+    # for releases, ASF Snapshot repo for snapshots). Integrity is ensured by the TLS
+    # connection to the repository host and Maven Central's GPG-signed artifacts.
+    # SHA-256 pinning is not used here because the FLUSS_VERSION build-arg varies per
+    # release; instead, trust is delegated to the repository's transport security.
+    curl -fL -o /opt/flink/lib/fluss-flink-${FLINK_VERSION}-${FLUSS_VERSION}.jar \
+        "${FLUSS_MAVEN_REPO_URL}/org/apache/fluss/fluss-flink-${FLINK_VERSION}/${FLUSS_VERSION}/fluss-flink-${FLINK_VERSION}-${FLUSS_VERSION}.jar"; \
+    curl -fL -o /opt/flink/lib/fluss-fs-s3-${FLUSS_VERSION}.jar \


FLUSS_VERSION is a required build arg, but the Dockerfile doesn’t validate it before constructing download URLs. If it’s omitted, the build will fail later with a confusing 404 from Maven/GitHub. Add an explicit check early in the RUN step (or provide a clear default) so failures are fast and actionable.

luoyuxia

@polyzos Thanks for the pr. I left minor comments. PTAL

luoyuxia · 2026-04-21T12:08:24Z

+    tags:
+      - 'v*'
+    branches:
+      - main


Do we really need to always trigger it on main branch changed?

Also, I'm thinking do we really need this action to build docker image since we will always need to build quick start image.

luoyuxia · 2026-04-21T12:12:14Z

+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}


have you already set the secrets？

luoyuxia · 2026-04-21T12:21:16Z

+    # release; instead, trust is delegated to the repository's transport security.
+    curl -fL -o /opt/flink/lib/fluss-flink-${FLINK_VERSION}-${FLUSS_VERSION}.jar \
+        "${FLUSS_MAVEN_REPO_URL}/org/apache/fluss/fluss-flink-${FLINK_VERSION}/${FLUSS_VERSION}/fluss-flink-${FLINK_VERSION}-${FLUSS_VERSION}.jar"; \
+    curl -fL -o /opt/flink/lib/fluss-fs-s3-${FLUSS_VERSION}.jar \


it depends on 1.0-SNAPSHOT artifacts from ASF snapshots, but I can’t find any workflow in this repo that publishes fluss-flink-2.2 / fluss-fs-s3 snapshots there. docker/quickstart-flink/Docker file downloads both jars from https://repository.apache.org/content/groups/snapshots, and the corresponding snapshot metadata endpoints currently return 404. As written, this means the new build-quickstart-flink job will fail on main pushes after merge.

Also, the same for the rc and release tag

We may need to fall back the previous way where we build and publish the docker image manually.

One quick way is just add the conent about quick start image bakc which is removed in #2672

luoyuxia · 2026-04-21T15:02:34Z

  "fullVersion": "0.10-SNAPSHOT",
  "shortVersion": "0.10",
-  "dockerVersion": "0.10-SNAPSHOT",
+  "dockerVersion": "latest-snapshot",


i think we don't need to change this

luoyuxia · 2026-04-21T15:12:29Z

+    tags:
+      - 'v*'
+    branches:
+      - main


Also, I'm thinking do we really need this action to build docker image since we will always need to build quick start image.

reintroduce quickstart

a46cdfb

luoyuxia requested review from Copilot and luoyuxia and removed request for Copilot April 21, 2026 12:04

Copilot started reviewing on behalf of luoyuxia April 21, 2026 12:05 View session

Copilot AI reviewed Apr 21, 2026

View reviewed changes

address copilot comments

16b5a51

luoyuxia reviewed Apr 21, 2026

View reviewed changes

address yuxias comments

873e9d8

luoyuxia reviewed Apr 21, 2026

View reviewed changes

	"paimonVersionShort": "1.3",
	"paimonVersionShort": "1.3",
	"mavenRepoUrl": "https://repository.apache.org/content/repositories/snapshots",

		# The Flink version bundled in the quickstart image. Update this when the
		# recommended Flink version for the quickstart changes.

-  # The Flink version bundled in the quickstart image. Update this when the
-  # recommended Flink version for the quickstart changes.
+  # The Flink version prefix bundled in the quickstart image.
+  # Keep this in sync with:
+  #  - website/fluss-versions.json (`quickstartFlinkDockerVersion`, typically in `next`)
+  #  - the website replacement logic fallback for the quickstart Flink version
+  # Update all of them together when the recommended quickstart Flink version changes.

Conversation

polyzos commented Apr 21, 2026

Uh oh!

polyzos commented Apr 21, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 21, 2026

Choose a reason for hiding this comment

Uh oh!

luoyuxia 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!

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