feat: ✨ Add version information endpoint and display in UI; update Dockerfile for metadata

Author: OidaTiftla

.github/workflows/docker-publish.yml

@@ -4,6 +4,11 @@ on:
   push:
     branches:
       - main
+    tags:
+      - 'v*'
+  pull_request:
+    branches:
+      - main
 
 permissions:
   contents: read
@@ -23,23 +28,44 @@ jobs:
         uses: docker/setup-buildx-action@v2
 
       - name: Log in to GitHub Container Registry
+        if: github.event_name != 'pull_request'
         uses: docker/login-action@v2
         with:
           registry: ghcr.io
           username: ${{ github.actor }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
-      - name: Set lowercase repository owner
-        id: setup
-        run: echo "owner_lower=$(echo '${{ github.repository_owner }}' | tr '[:upper:]' '[:lower:]')" >> $GITHUB_OUTPUT
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ghcr.io/${{ github.repository_owner }}/calendar-proxy
+          tags: |
+            # set latest tag for default branch
+            type=raw,value=latest,enable={{is_default_branch}}
+            # tag event
+            type=ref,event=tag
+            # branch event
+            type=ref,event=branch
+            # pr event
+            type=ref,event=pr
+            # set version tag for tags starting with v
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
 
       - name: Build and push Docker image (multi-arch)
         uses: docker/build-push-action@v4
         with:
           context: .
-          push: true
+          push: ${{ github.event_name != 'pull_request' }}
           platforms: linux/amd64,linux/arm64,linux/arm/v7,linux/386
-          tags: |
-            ghcr.io/${{ steps.setup.outputs.owner_lower }}/calendar-proxy:latest
-            ghcr.io/${{ steps.setup.outputs.owner_lower }}/calendar-proxy:${{ github.sha }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          build-args: |
+            VERSION=${{ fromJSON(steps.meta.outputs.json).labels['org.opencontainers.image.version'] }}
+            BUILD_DATE=${{ fromJSON(steps.meta.outputs.json).labels['org.opencontainers.image.created'] }}
+            COMMIT=${{ fromJSON(steps.meta.outputs.json).labels['org.opencontainers.image.revision'] }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
           file: Dockerfile

Dockerfile

@@ -22,6 +22,26 @@ RUN mkdir -p static && tailwindcss -i ./input.css --content ./index.html -o ./st
 # Runtime stage - minimal Python environment
 FROM python:3.13.7-slim AS runtime
 
+# Build arguments for metadata
+ARG VERSION=dev
+ARG BUILD_DATE
+ARG COMMIT
+
+# OCI Image Labels for better metadata
+LABEL org.opencontainers.image.title="Calendar Proxy" \
+      org.opencontainers.image.description="A secure proxy service that makes browser-only calendar links (like Office 365 shared calendars) accessible to calendar clients that can't authenticate or handle custom headers" \
+      org.opencontainers.image.version="${VERSION}" \
+      org.opencontainers.image.created="${BUILD_DATE}" \
+      org.opencontainers.image.revision="${COMMIT}" \
+      org.opencontainers.image.vendor="OidaTiftla" \
+      org.opencontainers.image.licenses="MIT" \
+      org.opencontainers.image.source="https://github.com/OidaTiftla/calendar-proxy"
+
+# Set environment variables for runtime access
+ENV APP_VERSION=${VERSION} \
+    APP_BUILD_DATE=${BUILD_DATE} \
+    APP_COMMIT=${COMMIT}
+
 # Create non-root user for security
 RUN groupadd --gid 1000 appuser && \
     useradd --uid 1000 --gid appuser --shell /bin/bash --create-home appuser

README.md

@@ -144,6 +144,7 @@ Open `http://<host>:8000/` in a browser to use the included `index.html` UI for
 
 - `GET /sub/{token}/{b64url}/{name}.ics` — subscription proxy endpoint.
 - `GET /healthz` — health check JSON response.
+- `GET /version` — version information JSON response (includes version, build date, and commit).
 - `GET /` — web UI for building calendar subscription URLs.
 - `GET /static/{path}` — static files (CSS, etc.) for the web UI.
 

src/app.py

@@ -96,7 +96,16 @@ def sanitize_url_for_logging(url: str) -> str:
 @app.on_event("startup")
 async def startup_event():
     """Initialize any startup tasks."""
+    # Get version info from environment variables
+    version = os.getenv("APP_VERSION", "dev")
+    build_date = os.getenv("APP_BUILD_DATE", "unknown")
+    commit = os.getenv("APP_COMMIT", "unknown")
+
     logging.info("Calendar Proxy starting up")
+    logging.info(f"Version: {version}")
+    logging.info(f"Build Date: {build_date}")
+    logging.info(f"Commit: {commit}")
+
     # Do initial cleanup of in-memory rate limiter
     if not redis_client:
         await _cleanup_inmem_limits()
@@ -375,13 +384,37 @@ def health():
     return {"status": "ok"}
 
 
+@app.get("/version")
+def version():
+    """Get version information"""
+    return {
+        "version": os.getenv("APP_VERSION", "dev"),
+        "build_date": os.getenv("APP_BUILD_DATE", "unknown"),
+        "commit": os.getenv("APP_COMMIT", "unknown")
+    }
+
+
 # Serve a small static index.html UI if present (file saved alongside app)
 @app.get("/", response_class=HTMLResponse)
 async def index():
     try:
         here = os.path.dirname(__file__)
         with open(os.path.join(here, "index.html"), "r", encoding="utf-8") as f:
-            return HTMLResponse(f.read())
+            html_content = f.read()
+
+        # Replace placeholders with actual version information
+        version = os.getenv("APP_VERSION", "dev")
+        build_date = os.getenv("APP_BUILD_DATE", "unknown")
+        commit = os.getenv("APP_COMMIT", "unknown")
+
+        # Truncate commit to 8 characters if it's not 'unknown'
+        commit_display = commit[:8] if commit != 'unknown' else commit
+
+        html_content = html_content.replace("{{APP_VERSION}}", version)
+        html_content = html_content.replace("{{APP_BUILD_DATE}}", build_date)
+        html_content = html_content.replace("{{APP_COMMIT}}", commit_display)
+
+        return HTMLResponse(html_content)
     except FileNotFoundError:
         return PlainTextResponse("Index not found", status_code=404)
 

src/index.html

@@ -229,6 +229,15 @@ <h1 class="text-3xl font-bold text-cyan-400 mb-2">Calendar Proxy</h1>
           </div>
         </div>
       </section>
+
+      <!-- Version Information -->
+      <div class="text-center mt-8 pt-6 border-t border-slate-700">
+        <p class="text-xs text-slate-500">
+          Version: <span class="text-slate-400">{{APP_VERSION}}</span> | Build:
+          <span class="text-slate-400">{{APP_BUILD_DATE}}</span> | Commit:
+          <span class="text-slate-400">{{APP_COMMIT}}</span>
+        </p>
+      </div>
     </main>
 
     <script>