ci: Add Docker publishing workflows and documentation for ASF releases #18

adityamparikh · 2025-11-09T04:50:10Z

.github/workflows/nightly-build.yml: Automated nightly builds
- Scheduled to run daily at 2 AM UTC
- Publishes to apache/solr-mcp-nightly on Docker Hub
- Creates source distributions for Apache nightlies infrastructure
.github/workflows/release-publish.yml: Official release workflow
- Manual trigger after ASF vote passes (72-hour voting period)
- Validates release prerequisites before publishing
- Publishes to apache/solr-mcp with semantic versioning
- Includes MCP registry integration for server discovery
- Supports ASF code signing infrastructure (when available)

Documentation

DOCKER_PUBLISHING.md: Complete Docker publishing guide
- Explains all publishing workflows and ASF compliance requirements
- Provides step-by-step release process instructions
- Includes troubleshooting guide and security considerations
- Documents authentication setup for various registries

GitHub workflows modified using Claude to address #15 (comment)

adityamparikh · 2025-11-09T20:19:42Z

@epugh @janhoy please advise if this would be according to your plans.

epugh · 2025-11-10T15:39:31Z

Thanks @adityamparikh... So, I suspect this is one of those changes that is tougher in the sense of we are interacting with ASF processes. So don't get frustrated ;-).

Now, I haven't done a docker deployment process. Does this process mirror what we have in https://github.com/apache/solr-docker ???

adityamparikh · 2025-11-10T19:15:06Z

From Claude's Review: The release process in this Solr MCP repository does not directly mirror the Apache Solr Docker repository, though both follow Apache Software Foundation (ASF) requirements. Here are the key findings:

Similarities (ASF Compliance)
Both repositories strictly adhere to ASF release requirements:

72-hour minimum voting period with 3+ binding PMC votes
Source distribution as the official release (Docker images are "convenience binaries")
GPG signing requirements for release artifacts
No pre-vote publishing of Docker images

Major Differences

Build System

Solr MCP: Uses Jib (Google's containerization plugin) - no Docker daemon needed
Solr Docker: Traditional Dockerfile approach built by Docker Official Images

Release Automation

Solr MCP: GitHub Actions workflows with manual triggers (release-publish.yml)
Solr Docker: Solr Release Wizard generates Dockerfiles, then automated PR to docker-library

Publishing Strategy

Solr MCP:
- Direct publishing to multiple registries (GHCR, Docker Hub)
- Includes MCP Registry integration
- Has dedicated nightly builds (nightly-build.yml)
Solr Docker:
- Only Docker Hub Official Images
- Requires Docker team approval
- No nightly builds

Dockerfile Management

Solr MCP: Single Dockerfile embedded in Jib configuration, can be modified
Solr Docker: Immutable Dockerfiles after release, generated from main Solr repo

Conclusion
The Solr MCP release process appears to be inspired by ASF best practices (which Solr Docker also follows) but is independently designed for its specific use case as an MCP server. It's optimized for:

Modern containerization (Jib instead of traditional Docker)
MCP ecosystem integration
Greater publishing flexibility
Automated nightly builds

The documentation structure and ASF compliance suggest the team studied Apache release requirements but created their own workflow suited to the project's needs rather than directly mirroring Solr Docker's process.

janhoy

AI code tools are great, but I feel better discussing with a human than a raw AI output, there is always some level of noise in those reponses.

I have not reviewed the entire PR. So I just add some preliminary comments here. Some nice GH Action use for the release process, I like that.

janhoy · 2025-11-09T21:33:22Z

.github/workflows/release-publish.yml

+        description: 'Release version (e.g., 1.0.0)'
+        required: true
+        type: string
+        # Which release candidate was approved (used to check out the exact tag)


The indentation of the comments are confusing, should be in line with the block below

janhoy · 2025-11-10T21:08:50Z

dev-docs/DOCKER_PUBLISHING.md

+
+1. Contact ASF INFRA for setup requirements
+2. Enable in release workflow with `sign_with_asf_infra: true`
+3. Signatures will be automatically applied to artifacts


Here is the description from INFRA about using GitHub actions for signing artifacts: https://infra.apache.org/release-signing.html#automated-release-signing

First we need to assess whether this repo qualifies, where the crucial part is reproducible builds. If it does, the release process must include a reproduction of the same artifacts (with same SHA) on developer's hardware. Etc. Once we feel all boxes are checked we can file an INFRA Jira issue to apply for signing secret to be deployed to the proejct.

Do we think that going down the https://news.apache.org/foundation/entry/apache-trusted-releases-platform-begins-second-alpha is a rat hole? It would be nice if we don't need to do the "developer's hardware" step....

Here is the description from INFRA about using GitHub actions for signing artifacts: https://infra.apache.org/release-signing.html#automated-release-signing

First we need to assess whether this repo qualifies, where the crucial part is reproducible builds. If it does, the release process must include a reproduction of the same artifacts (with same SHA) on developer's hardware. Etc. Once we feel all boxes are checked we can file an INFRA Jira issue to apply for signing secret to be deployed to the proejct.

gradle build will produce reproducible jars and the jib plugin will produce reproducible docker images.
https://github.com/apache/solr-mcp/pull/18/files#diff-c6d47dacf31662f6791d0cf218b1d34ee0ab48348c037819431cdd40e3fc23e4R163
has placeholder for automated release signing which will have to be implemented.

It says that all projects are eligible for joining the 2nd Alpha of the ATR. Since we already have reproducible build, this could be interesting. The ATR project aims to automate everyting, voting and convenience binary distribution to various package repos, probably also Docker further down the road. For now it seems like it will handle the release process itself and let you download the artifact for manual release at the end.

To me it looks like requesting a "Github actions" signing key option is different from joining Apache-Trusted-Releases alpha. Perhaps even possible to combine?

do we need anyone else's inputs or suggestions in order to proceed?

They are discussing adding a new github action to publish artifacts to ATR https://the-asf.slack.com/archives/C049WADAAQG/p1762958477034239?thread_ts=1762950994.138959&cid=C049WADAAQG

Perhaps you can float a dev@ [DISCUSS] list thread outlining the proposed release procedure and mention that we consider ATR with CI signing. Then we'll have some broader decision on what to do before starting to apply or order stuff from INFRA.

janhoy · 2025-11-10T21:14:40Z

.github/workflows/release-publish.yml

+        run: |
+          # Also publish to GitHub Container Registry
+          ./gradlew jib \
+            -Djib.to.image=ghcr.io/${{ github.repository_owner }}/solr-mcp:${{ inputs.release_version }} \


If we're anyway publishing nightlies to hub, is there a particular benefit of also using ghcr?

If we have established process around publishing to one or the other, we can follow the same here. Publishing release gives options to make it available where the users are able to access and keeping nightly releases to only one.

epugh · 2025-11-10T22:07:55Z

I don't have a lot of expertise in Docker builds. It looks like the model in solr-docker is that the receipe, the Dockerfile, is checked in, it somehow goes to Dockerhub, and that the actual image is built in Docker hub? Whereas, in apps I've done, I build the Docker image locally, and then push it up to Docker hub. I think that is more the model that we have here, excpet instead of building the image locally, it would be done by GHA?

janhoy · 2025-11-10T22:26:24Z

Solr was early with docker image without a prefix (org), that's why that workflow is special, and the solr image is built on Docker's infrastructure and is auto refreshed by them. But they don't allow new images in, and frankly an apache/ prefix is expected, and the workflow is straight forward, build the image somewhere and push.

If we want to re-build once in a while to take advantage of newer base image, we could perhaps setup a scheduled workflow every Sunday or something that will check if upstream has any changes, and if so, re-build and re-publish the image. Preferences vary here, since that violates the immutable tag principle. But users can shield themselves from such changes by pinning SHA. Not a priority anyway.

epugh · 2025-11-11T14:05:57Z

Solr was early with docker image without a prefix (org), that's why that workflow is special, and the solr image is built on Docker's infrastructure and is auto refreshed by them. But they don't allow new images in, and frankly an apache/ prefix is expected, and the workflow is straight forward, build the image somewhere and push.

If we want to re-build once in a while to take advantage of newer base image, we could perhaps setup a scheduled workflow every Sunday or something that will check if upstream has any changes, and if so, re-build and re-publish the image. Preferences vary here, since that violates the immutable tag principle. But users can shield themselves from such changes by pinning SHA. Not a priority anyway.

Thanks for the back story on the Solr docker image.

I think that rebuilding for newer base image is probably overkill for what this project does... Plus, hopefully it's an active project and has periodic releases to pick up the new releases. --> I am also always nervous about adding more build tooling then we can feasibly support!

adityamparikh · 2025-11-13T17:35:56Z

@epugh @janhoy I created Jira ticket for Infra to get signing key https://issues.apache.org/jira/browse/INFRA-27404
Please review.

… and nightlies path; mark Docker images as convenience binaries; update MCP label snippet; extend release checklist and policy notes

…agement, nightly builds, and publishing steps

…egistry

…mode

docs: http-instructions

adityamparikh changed the title ~~Add Docker publishing workflows and documentation for ASF releases~~ ci: Add Docker publishing workflows and documentation for ASF releases Nov 9, 2025

janhoy reviewed Nov 10, 2025

View reviewed changes

adityamparikh added 5 commits November 18, 2025 17:18

docs: add a tutorial

0d6efda

docs: clarify ASF-compliant release process; fix nightly image naming…

f0030bf

… and nightlies path; mark Docker images as convenience binaries; update MCP label snippet; extend release checklist and policy notes

docs: enhance GitHub workflows with detailed comments for release man…

7ce1715

…agement, nightly builds, and publishing steps

docs: remove outdated GitHub Actions workflow for publishing to MCP R…

e8b3a5c

…egistry

feat: Create atr-release.yml for Apache Trusted Releases

0a6d6cd

adityamparikh force-pushed the docs/release-process-clarifications branch from 36cfd48 to 0a6d6cd Compare November 18, 2025 22:18

adityamparikh added 2 commits November 26, 2025 20:38

docs: update README with instructions for running MCP server in HTTP …

ae1bfe7

…mode

Merge pull request #18 from adityamparikh/http-instructions

724000f

docs: http-instructions

ci: Add Docker publishing workflows and documentation for ASF releases #18

Are you sure you want to change the base?

ci: Add Docker publishing workflows and documentation for ASF releases #18

Uh oh!

Conversation

adityamparikh commented Nov 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation

Uh oh!

adityamparikh commented Nov 9, 2025

Uh oh!

epugh commented Nov 10, 2025

Uh oh!

adityamparikh commented Nov 10, 2025

Uh oh!

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

Choose a reason for hiding this comment

Uh oh!

epugh commented Nov 10, 2025

Uh oh!

janhoy commented Nov 10, 2025

Uh oh!

epugh commented Nov 11, 2025

Uh oh!

adityamparikh commented Nov 13, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

adityamparikh commented Nov 9, 2025 •

edited

Loading