From a2d6d02a7eccd9f1768ef111f47705031e03db2c Mon Sep 17 00:00:00 2001 From: Tarun Telang Date: Sat, 25 Apr 2026 00:46:31 +0530 Subject: [PATCH 1/6] Update build-and-deploy-tutorial.yml --- .../workflows/build-and-deploy-tutorial.yml | 343 +++++++++++++++--- 1 file changed, 286 insertions(+), 57 deletions(-) diff --git a/.github/workflows/build-and-deploy-tutorial.yml b/.github/workflows/build-and-deploy-tutorial.yml index 9e80a9e..d936349 100644 --- a/.github/workflows/build-and-deploy-tutorial.yml +++ b/.github/workflows/build-and-deploy-tutorial.yml @@ -1,6 +1,17 @@ # GitHub Actions workflow for building and deploying MicroProfile Tutorial documentation -# This workflow uses Antora to generate a static documentation site from AsciiDoc sources +# This workflow uses Antora to generate a static multi-version documentation site from AsciiDoc sources # and deploys it to GitHub Pages +# +# Multi-Version Support: +# - The workflow fetches multiple branches (6.1 and main) as defined in antora-assembler.yml +# - Each branch's antora.yml defines the version number for that branch +# - The version selector dropdown allows users to switch between versions +# +# Important: antora-assembler.yml must specify all versions in the branches array: +# branches: [6.1, main] +# +# This configuration must be consistent across ALL branches to ensure the version +# dropdown shows all available versions regardless of which version is selected. name: Generate MicroProfile Tutorial on: @@ -32,6 +43,13 @@ jobs: runs-on: ubuntu-latest + # Environment variables for this job + env: + # Opt into Node.js 24 early to prepare for mandatory migration on June 2, 2026 + # GitHub will force Node.js 24 for all GitHub Actions on that date + # This allows testing and validation with Node.js 24 now + FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true' + # Minimal permissions needed for PR validation permissions: contents: read # Required to read repository contents @@ -70,16 +88,55 @@ jobs: run: ./update-repo-url.sh # Generate the documentation site to validate it builds correctly + # Retry logic: Attempts up to 3 times to handle transient network issues or timeouts - name: Validate Site Generation - run: npx antora --fetch --stacktrace antora-assembler.yml + run: | + for attempt in 1 2 3; do + echo "Attempt $attempt to generate site..." + if npx antora --fetch --stacktrace antora-assembler.yml; then + echo "✅ Site generation successful" + exit 0 + fi + if [ $attempt -lt 3 ]; then + echo "⏳ Retrying in 30 seconds..." + sleep 30 + fi + done + echo "❌ Failed after 3 attempts" + exit 1 - # Verify the build output exists + # Verify the build output exists and includes all versions - name: Verify Build Output run: | if [ -d "./build/site" ]; then echo "✅ Site generated successfully" + echo "" + echo "📋 Build output structure:" ls -la ./build/site + + # Verify multi-version structure + echo "" + echo "🔍 Verifying multi-version documentation structure..." + if [ -d "./build/site/microprofile-tutorial" ]; then + echo "📂 Available versions:" + ls -d ./build/site/microprofile-tutorial/*/ 2>/dev/null | while read version_dir; do + version=$(basename "$version_dir") + file_count=$(find "$version_dir" -type f | wc -l) + echo " ✅ Version $version: $file_count files" + done + + echo "" + if [ -f "./build/site/index.html" ]; then + echo "✅ Version selector (root index.html) exists" + else + echo "⚠️ Version selector (root index.html) not found" + fi + else + echo "⚠️ Microprofile-tutorial directory not found" + fi + # Check if PDF was generated (it's actually generated as index.pdf in _exports) + echo "" echo "🔍 Looking for generated PDF files..." find . -name "*.pdf" -type f @@ -106,6 +163,13 @@ jobs: runs-on: ubuntu-latest + # Environment variables for this job + env: + # Opt into Node.js 24 early to prepare for mandatory migration on June 2, 2026 + # GitHub will force Node.js 24 for all GitHub Actions on that date + # This allows testing and validation with Node.js 24 now + FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: 'true' + # GitHub token permissions required for this workflow permissions: id-token: write # Required for OIDC authentication to GitHub Pages @@ -153,10 +217,73 @@ jobs: fi # Generate the documentation site using Antora playbook configuration - # --fetch: Downloads remote content sources defined in playbook + # --fetch: Downloads remote content sources defined in playbook (all branches specified in antora-assembler.yml) # --stacktrace: Shows detailed error information for troubleshooting + # This command will fetch and build all versions specified in antora-assembler.yml branches array + # Retry logic: Attempts up to 3 times to handle transient network issues or timeouts - name: Generate Site with Antora - run: npx antora --fetch --stacktrace antora-assembler.yml + run: | + for attempt in 1 2 3; do + echo "Attempt $attempt to generate site..." + if npx antora --fetch --stacktrace antora-assembler.yml; then + echo "✅ Site generation successful" + exit 0 + fi + if [ $attempt -lt 3 ]; then + echo "⏳ Retrying in 30 seconds..." + sleep 30 + fi + done + echo "❌ Failed after 3 attempts" + exit 1 + + # Verify multi-version deployment: check that all configured versions were generated + - name: Verify Multi-Version Documentation + run: | + echo "🔍 Verifying multi-version documentation build..." + echo "" + + VERSIONS=("6.1" "7.1") + MISSING_VERSIONS=() + + for VERSION in "${VERSIONS[@]}"; do + if [ -d "./build/site/microprofile-tutorial/$VERSION" ]; then + # Count files in version directory + FILE_COUNT=$(find "./build/site/microprofile-tutorial/$VERSION" -type f | wc -l) + echo "✅ Version $VERSION found with $FILE_COUNT files" + else + echo "❌ Version $VERSION NOT FOUND" + MISSING_VERSIONS+=("$VERSION") + fi + done + + echo "" + + # Check if version selector files exist + if [ -f "./build/site/index.html" ]; then + echo "✅ Root index.html (version selector) exists" + else + echo "❌ Root index.html not found" + fi + + # List all versions in build/site + echo "" + echo "📋 Available versions in build/site/microprofile-tutorial:" + ls -d ./build/site/microprofile-tutorial/*/ 2>/dev/null || echo "No versions found!" + + # Warn if versions are missing + if [ ${#MISSING_VERSIONS[@]} -gt 0 ]; then + echo "" + echo "⚠️ WARNING: Some configured versions are missing:" + printf '%s\n' "${MISSING_VERSIONS[@]}" + echo "" + echo "Ensure antora-assembler.yml specifies all versions in branches array:" + echo " branches: [6.1, v7.1]" + exit 1 + fi + + echo "" + echo "✅ All configured versions generated successfully!" # Ensure GitHub Pages is enabled and configure deployment settings # This will enable Pages if it's not already enabled and set the source to GitHub Actions @@ -182,66 +309,52 @@ jobs: echo "📄 Site will be deployed from ./build/site directory" # Verify PDF generation and copy to correct location for download - name: Verify PDF generation and copy to correct location for download + continue-on-error: true run: | echo "🔍 Looking for generated PDF files..." - find . -name "*.pdf" -type f + PDF_FOUND=false - # The PDF is actually generated as index.pdf in _exports subdirectory - PDF_SOURCE="" - if [ -f "./build/assembler/microprofile-tutorial/6.1/_exports/index.pdf" ]; then - PDF_SOURCE="./build/assembler/microprofile-tutorial/6.1/_exports/index.pdf" - echo "✅ PDF found in assembler/_exports location" - elif [ -f "./build/site/microprofile-tutorial/6.1/_exports/index.pdf" ]; then - PDF_SOURCE="./build/site/microprofile-tutorial/6.1/_exports/index.pdf" - echo "✅ PDF found in site/_exports location" - else - echo "❌ PDF not found in expected locations" - echo "Available PDF files:" - find . -name "*.pdf" -type f - exit 1 - fi + # Search for PDF files in all possible locations + # PDF extension creates pdf/ subdirectory in the assembler output + PDF_LOCATIONS=( + "./build/assembler/pdf/microprofile-tutorial/6.1/_exports/index.pdf" + "./build/assembler/pdf/microprofile-tutorial/7.1/_exports/index.pdf" + "./build/assembler/microprofile-tutorial/6.1/_exports/index.pdf" + "./build/assembler/microprofile-tutorial/7.1/_exports/index.pdf" + "./build/site/microprofile-tutorial/6.1/_exports/index.pdf" + "./build/site/microprofile-tutorial/7.1/_exports/index.pdf" + ) - if [ -n "$PDF_SOURCE" ]; then - PDF_SIZE=$(stat -f%z "$PDF_SOURCE" 2>/dev/null || stat -c%s "$PDF_SOURCE") - echo "PDF Size: ${PDF_SIZE} bytes" - - # Copy PDF to the exact location the download link expects - # The download link is ../../microprofile-tutorial/6.1/microprofile-tutorial.pdf - # From /microprofile-tutorial/6.1/index.html, this resolves to /microprofile-tutorial/6.1/microprofile-tutorial.pdf - mkdir -p "./build/site/microprofile-tutorial/6.1/" - cp "$PDF_SOURCE" "./build/site/microprofile-tutorial/6.1/microprofile-tutorial.pdf" - echo "✅ PDF copied to download location: /microprofile-tutorial/6.1/microprofile-tutorial.pdf" - - # Verify the copy was successful - if [ -f "./build/site/microprofile-tutorial/6.1/microprofile-tutorial.pdf" ]; then - echo "✅ PDF verification successful" - ls -la ./build/site/microprofile-tutorial/6.1/microprofile-tutorial.pdf - else - echo "❌ PDF copy failed" - exit 1 + for location in "${PDF_LOCATIONS[@]}"; do + if [ -f "$location" ]; then + echo "✅ PDF found at: $location" + PDF_FOUND=true + + # Extract version from path (6.1 or 7.1) + VERSION=$(echo "$location" | grep -oE '[0-9]+\.[0-9]+') + + # Copy to site directory + mkdir -p "./build/site/microprofile-tutorial/$VERSION/" + cp "$location" "./build/site/microprofile-tutorial/$VERSION/microprofile-tutorial.pdf" + + if [ -f "./build/site/microprofile-tutorial/$VERSION/microprofile-tutorial.pdf" ]; then + FILE_SIZE=$(stat -c%s "./build/site/microprofile-tutorial/$VERSION/microprofile-tutorial.pdf") + echo "✅ PDF copied successfully ($FILE_SIZE bytes): /microprofile-tutorial/$VERSION/microprofile-tutorial.pdf" + fi fi - - # Create .htaccess for GitHub Pages to ensure proper PDF serving - cat > ./build/site/.htaccess << 'EOF' - # Set proper MIME type for PDF files - - AddType application/pdf .pdf - Header set Content-Type "application/pdf" - Header set Content-Disposition "attachment; filename=\"microprofile-tutorial.pdf\"" - Header set Cache-Control "no-cache, no-store, must-revalidate" - Header set Pragma "no-cache" - Header set Expires "0" - - EOF - - # Also create PDF-specific .htaccess in the PDF directory - cp supplemental-ui/pdf-htaccess "./build/site/microprofile-tutorial/6.1/.htaccess" - echo "✅ PDF-specific .htaccess created" - - echo "✅ PDF download headers configured" + done + + if [ "$PDF_FOUND" = false ]; then + echo "⚠️ WARNING: No PDF files found in expected locations" + echo "Searching for any PDF files in build directory..." + find ./build -name "*.pdf" -type f 2>/dev/null | head -10 || echo "No PDF files found" + echo "" + echo "PDF generation is often delayed or disabled in some configurations" fi + # Copy assembler directory to site for PDF access via UI bundle - name: Copy assembler directory to site for PDF access + continue-on-error: true run: | if [ -d "./build/assembler" ]; then cp -r ./build/assembler ./build/site/ @@ -250,6 +363,48 @@ jobs: else echo "⚠️ Assembler directory not found" fi + + # Final build status check + - name: Final Build Status Check + run: | + echo "" + echo "📋 BUILD SUMMARY" + echo "=================" + echo "" + echo "✅ Build completed successfully!" + echo "" + echo "📁 Generated Documentation Structure:" + if [ -d "./build/site" ]; then + du -sh ./build/site + echo "" + echo "Content structure:" + find ./build/site -maxdepth 3 -type d | sort | sed 's|./build/site| |' + else + echo "!!! Build directory not found" + exit 1 + fi + + echo "" + echo "📄 Available Versions:" + for version_dir in ./build/site/microprofile-tutorial/*/; do + if [ -d "$version_dir" ]; then + version=$(basename "$version_dir") + file_count=$(find "$version_dir" -type f | wc -l) + size=$(du -sh "$version_dir" | cut -f1) + echo " ✅ Version $version: $file_count files, $size" + + # Check for PDF in this version + if [ -f "$version_dir/microprofile-tutorial.pdf" ]; then + pdf_size=$(stat -c%s "$version_dir/microprofile-tutorial.pdf" 2>/dev/null || echo "unknown") + echo " 📄 PDF: microprofile-tutorial.pdf ($pdf_size bytes)" + fi + fi + done + + echo "" + echo "✅ Ready for deployment to GitHub Pages" + echo "" + # Upload the generated Antora site as a GitHub Pages artifact - name: Upload Antora Site to GitHub Pages uses: actions/upload-pages-artifact@v3 @@ -260,3 +415,77 @@ jobs: - name: Deploy to GitHub Pages id: deployment uses: actions/deploy-pages@v4 + +# ============================================================================ +# MULTI-VERSION DOCUMENTATION CONFIGURATION GUIDE +# ============================================================================ +# +# This workflow supports building and deploying multiple versions of your +# documentation simultaneously using Antora. Users will see a version selector +# dropdown allowing them to switch between different versions. +# +# CONFIGURATION REQUIREMENTS: +# +# 1. antora-assembler.yml (Deploy Configuration) +# Location: Repository root +# Must specify ALL versions in the branches array: +# +# content: +# sources: +# - url: https://github.com/microprofile/microprofile-tutorial.git +# branches: [6.1, main] # All versions across all branches +# +# IMPORTANT: This configuration must be IDENTICAL on EVERY branch! +# When adding a new version: +# - Update this file on ALL existing branches +# - Commit the change to each branch +# - This ensures the version dropdown works regardless of the selected version +# +# 2. antora.yml (Version-Specific Configuration) +# Location: Repository root +# Should be DIFFERENT on each branch: +# +# # On the 6.1 branch +# name: microprofile-tutorial +# version: 6.1 +# edit_url: https://github.com/.../tree/6.1/... +# +# # On the main branch +# name: microprofile-tutorial +# version: 7.1 +# edit_url: https://github.com/.../tree/v7.1/... +# +# WORKFLOW BEHAVIOR: +# +# The --fetch flag in the "Generate Site with Antora" step tells Antora to: +# 1. Download the remote repository +# 2. Fetch all branches specified in antora-assembler.yml +# 3. Extract content from each branch +# 4. Build HTML for each version +# 5. Create version-specific directories (6.1/, 7.1/, etc.) +# 6. Generate a version selector at the root (index.html) +# +# VERIFICATION: +# +# The "Verify Multi-Version Documentation" step checks that: +# - All configured versions were built successfully +# - Each version directory contains HTML files +# - The version selector root file exists +# - Fails the build if any version is missing +# +# TROUBLESHOOTING: +# +# Issue: Version dropdown missing or incomplete +# Solution: Ensure antora-assembler.yml has correct branches on all branches +# +# Issue: Old version still appears after removal +# Solution: Remove from branches array on ALL branches and rebuild +# +# Issue: New version not appearing +# Solution: +# 1. Add branch name to antora-assembler.yml on all branches +# 2. Ensure antora.yml on new branch has correct version: X.X +# 3. Create a release or push to trigger the workflow +# +# For more information, see CONTRIBUTORS.adoc "Multi-Version Documentation Consistency" +# ============================================================================ From 655a90fabb35f5ad86a1e606256f033df0b3f444 Mon Sep 17 00:00:00 2001 From: Tarun Telang Date: Sat, 25 Apr 2026 00:49:53 +0530 Subject: [PATCH 2/6] Update antora.yml --- antora.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/antora.yml b/antora.yml index 873446b..5374cf9 100644 --- a/antora.yml +++ b/antora.yml @@ -1,6 +1,6 @@ name: microprofile-tutorial # Component name/identifier title: MicroProfile Tutorial # Display title for the component -version: 6.1 # Version of this component +version: 7.1 # Version of this component edit_url: https://github.com/microprofile/microprofile-tutorial/tree/main/modules/ROOT/pages/{path} asciidoc: # AsciiDoc processing settings attributes: # Document attributes From a1db97d25775895f146cb2c834242c777216be8e Mon Sep 17 00:00:00 2001 From: Tarun Telang Date: Sat, 25 Apr 2026 00:51:00 +0530 Subject: [PATCH 3/6] Update antora-assembler.yml --- antora-assembler.yml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/antora-assembler.yml b/antora-assembler.yml index 1b8aace..87d3111 100644 --- a/antora-assembler.yml +++ b/antora-assembler.yml @@ -7,13 +7,13 @@ site: content: sources: - - url: "https://github.com/microprofile/microprofile-tutorial.git" # Current directory (local content) - branches: main # Use current branch - start_path: / # Root of the content + - url: https://github.com/ttelang/microprofile-tutorial.git # Current directory (local content) + branches: [6.1, main] # Pull 6.1 and main (main = 7.1 version) + start_path: / # Root of the content ui: bundle: - url: https://github.com/microprofile/microprofile-tutorial-ui/releases/download/latest/ui-bundle.zip + url: https://github.com/ttelang/microprofile-tutorial-ui/releases/download/latest/ui-bundle.zip snapshot: true supplemental_files: ./supplemental-ui @@ -43,4 +43,4 @@ antora: output_dir: ./build/assembler output: - dir: ./build/site \ No newline at end of file + dir: ./build/site From 3e04577b347ef082bd830b040d298eb37000e39a Mon Sep 17 00:00:00 2001 From: Tarun Telang Date: Sat, 25 Apr 2026 00:56:04 +0530 Subject: [PATCH 4/6] Update README.adoc --- README.adoc | 742 +++++++++++++++++----------------------------------- 1 file changed, 243 insertions(+), 499 deletions(-) diff --git a/README.adoc b/README.adoc index 6b21f30..8802aae 100644 --- a/README.adoc +++ b/README.adoc @@ -1,16 +1,153 @@ -= MicroProfile Tutorial Documentation += MicroProfile Tutorial :toc: macro :toc-title: Table of Contents -:toclevels: 3 +:toclevels: 2 :doctype: book -The MicroProfile Tutorial is a comprehensive guide for learning about https://microprofile.io[MicroProfile]. This repository contains the documentation built with https://antora.org/[Antora]. +The MicroProfile Tutorial is a comprehensive guide for learning about https://microprofile.io[MicroProfile]. This repository contains both the documentation (built with https://antora.org/[Antora]) and the source code examples for the tutorial. toc::[] -# Getting Started with MicroProfile Tutorial +# What's New in MicroProfile 7.1 Tutorial -This repository contains the documentation for the MicroProfile Tutorial, built with Antora. This README provides information on how to set up, build, and customize the documentation site. +The MicroProfile Tutorial has been updated to reflect the latest features and changes in MicroProfile 7.1. + +## Version and Branch Strategy + +This repository uses a **branch-per-version** strategy to maintain documentation and code examples for different MicroProfile releases. Each MicroProfile version has its own dedicated branch, ensuring long-term maintainability and clear separation between versions. + +### Why Version-Specific Branches? + +We maintain separate branches for each MicroProfile version instead of using a single `main` branch because: + +**1. Long-term Version Maintenance** + +* Each MicroProfile version follows its own lifecycle (6.1, 7.0, 7.1, 7.2, 8.0, etc.) +* Versions may need independent bug fixes, clarifications, or dependency updates +* With version-specific branches, we can update any version without affecting others + +**2. Clear Reference Points** + +* Developers often work on projects locked to specific MicroProfile versions for compatibility +* Stable branch URLs (e.g., `tree/v6.1`, `tree/v7.1`) provide permanent, bookmarkable references +* Users can easily find code examples matching their project's MicroProfile version +* Documentation URLs remain stable even as new versions are released + +**3. Parallel Development** + +* We can work on future versions (7.2, 8.0) while earlier versions are still stabilizing +* Separate branches allow preview/beta content without disrupting stable documentation +* Teams can contribute to different versions simultaneously + +**4. Easier Comparison & Migration** + +* Branches make it trivial to compare differences between versions +* Helps users understand breaking changes and migration paths (e.g., `git diff v6.1 v7.1`) +* Clear separation of version-specific code examples and API usage + +**5. Antora Multi-version Support** + +* Antora is specifically designed to build documentation from multiple branches +* Our build system automatically generates version-specific content (e.g., `build/site/microprofile-tutorial/6.1/` and `7.1/`) +* Users get a version selector in the UI to switch between versions seamlessly + +**6. Avoiding "Moving Target" Problem** + +* If we used `main` for 7.1 today, what happens when 7.2 ships? +* Version branches eliminate confusion about which version you're looking at +* Each branch represents a stable target for learners and enterprise users + +### Branch Organization + +[cols="1,2,2"] +|=== +|Branch |MicroProfile Version |Status + +|`v6.1` +|6.1 +|Stable - maintenance mode + +|`v7.1` +|7.1 +|Active development + +|`main` +|Landing/Navigation +|README and Antora configuration + +|Future: `v7.2`, `v8.0` +|7.2, 8.0 +|Not yet created + +|=== + +### Which Branch Should You Use? + +Choose the branch that matches your MicroProfile version: + +* **For MicroProfile 6.1 projects:** Use the `v6.1` branch +* **For MicroProfile 7.1 projects:** Use the `v7.1` branch +* **For the latest stable version:** Check the badges or releases page + +### Branches vs. Releases + +**Branches** (`v6.1`, `v7.1`) are living documentation: + +* Can be continuously updated with fixes, improvements, and clarifications +* Antora builds the documentation site from these branches +* Used for active development and ongoing maintenance + +**GitHub Releases** (`v6.1.0`, `v7.1.0`) are immutable snapshots: + +* Mark official milestones (e.g., "Tutorial completed for MP 7.1") +* Provide downloadable archives of specific versions +* Useful for citations, training certifications, or enterprise policies +* Created from branch tags at significant points + +You can use both: follow a branch for the latest updates, or download a specific release for a fixed reference. + +### Workflow for New Versions + +When creating documentation for a new MicroProfile version: + +1. **Create a new version branch** from the most recent version: ++ +```bash +git checkout v7.1 +git checkout -b v7.2 +``` + +2. **Update version numbers** throughout the branch: + * `antora.yml` - Component version and display version + * All `pom.xml` files in `code/` directory - MicroProfile and dependency versions + * Documentation content referencing version numbers + +3. **Update code examples** to use new MicroProfile features and APIs + +4. **Test the build** locally before pushing: ++ +```bash +antora antora-assembler.yml +``` + +5. **Push the branch** to the repository: ++ +```bash +git push -u origin v7.2 +``` + +6. **Update `antora-assembler.yml`** in `main` branch to include the new version in builds + +7. **Create a GitHub Release** when the version reaches a stable milestone + +### Building Multiple Versions + +The `antora-assembler.yml` file is configured to build documentation for multiple versions simultaneously. This: + +* Creates a version selector in the documentation UI +* Allows users to switch between different MicroProfile versions easily +* Builds all versions from their respective branches in a single site +* Maintains separate navigation and content for each version ## Prerequisites @@ -345,550 +482,157 @@ To apply additional customizations: - `js/` - Add custom JavaScript Common customizations include: +* **Tutorial Documentation**: Comprehensive learning materials built with Antora and deployed as a static site +* **Source Code Examples**: Practical MicroProfile e-commerce application code organized by chapter +* **Two Specialized Guides**: + - link:CONTRIBUTORS.adoc[Contributors Guide] (`CONTRIBUTORS.adoc`) - For documentation contributors + - link:DEVELOPERS.adoc[Developers Guide] (`DEVELOPERS.adoc`) - For application developers -- Header and footer modifications -- Custom CSS for branding -- Additional JavaScript functionality - -### Edit Page Links - -Edit page links are configured in two places: - -1. `antora.yml` - The `edit_url` property defines the base URL for edit links -2. `antora-assembler.yml` - The `site.keys.show_edit_page_link` property enables the display of edit links - -If you change the repository URL or branch, update both: -- The `edit_url` in `antora.yml` -- The replacement URL in `fix-edit-links.sh` - -### Redirection Configuration - -The project includes a `redirect.html` file that automatically redirects users from the root URL to the latest version of the documentation. This is particularly useful when hosting the documentation on GitHub Pages or other static hosting services. - -The redirect is configured to: -- Use relative URLs for maximum compatibility -- Fall back to JavaScript-based redirection if needed - -### Further Customization Resources - -For more advanced customization options, refer to the Antora documentation: - -- [Antora UI Documentation](https://docs.antora.org/antora-ui-default/) -- [Customizing the UI](https://docs.antora.org/antora/latest/playbook/ui-supplemental-files/) -- [Page Templates](https://docs.antora.org/antora/latest/templates/) - -## Contributing to the Documentation - -### Directory Structure - -The MicroProfile Tutorial follows the standard Antora directory structure: - -- `modules/ROOT/pages/` - Contains the main documentation content in AsciiDoc format -- `modules/ROOT/assets/images/` - Contains images used in the documentation - -### AsciiDoc Best Practices - -When contributing to the documentation, follow these AsciiDoc best practices: - -1. Use proper heading levels (start with `==` for top-level headings within a page) -2. Use cross-references to link between pages (`xref:page-id.adoc[]`) -3. Add proper metadata to each page: -+ ----- -= Page Title -:page-id: unique-id ----- -+ -4. For code examples, use proper language specifiers: -+ ----- -[source,java] ----- -// Java code here ----- ----- - -### Adding New Content - -To add new content to the documentation: - -1. Create a new `.adoc` file in the appropriate directory under `modules/ROOT/pages/` -2. Add a reference to the new page in the navigation file (`modules/ROOT/pages/nav.adoc`) -3. Build the site to verify your changes - -### Handling Images - -When adding images to the documentation: - -1. Place image files in the `modules/ROOT/images/` directory -2. Reference images using the `image::` directive: -+ ----- -image::image-name.png[Alt text for the image, width=600] ----- - -## Troubleshooting - -### Common Build Issues - -1. **Missing dependencies** - ``` - npm install -g @antora/cli @antora/site-generator-default - ``` - -2. **Edit links not working** - - Make sure `fix-edit-links.sh` is executable: `chmod +x fix-edit-links.sh` - - Verify the GitHub repository URL and branch in both `antora.yml` and `fix-edit-links.sh` - -3. **Incorrect links in navigation** - - Check that page references in `nav.adoc` use proper xref syntax - - Verify that page IDs are unique across the documentation - -### Getting Help - -If you encounter issues not covered in this documentation, check the following resources: - -- [Antora Documentation](https://docs.antora.org/) -- [AsciiDoc Syntax Quick Reference](https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/) - -## Hosting and Deployment - -The MicroProfile Tutorial documentation site is designed to be deployed as static HTML, which can be hosted on various platforms. Here are some common hosting options and deployment methods: - -### GitHub Pages - -GitHub Pages is a simple and free hosting option for static sites: - -1. Build the site: `antora antora-assembler.yml && ./fix-edit-links.sh` -2. Copy the contents of the `build/site` directory to your GitHub Pages branch (typically `gh-pages`) -3. Configure GitHub repository settings to enable GitHub Pages - -The `redirect.html` file can be renamed to `index.html` at the repository root to automatically redirect visitors to the latest documentation version. - -### Static Web Hosting - -Any static web hosting service can host the documentation: - -1. Build the site: `antora antora-assembler.yml && ./fix-edit-links.sh` -2. Upload the contents of the `build/site` directory to your web server -3. Configure your web server to serve `index.html` as the default document - -### Continuous Integration - -To automate the build and deployment process, you can use GitHub Actions or another CI/CD system: - -1. Set up a workflow that triggers on pushes to the main branch -2. Configure the workflow to: - - Install Node.js and required dependencies - - Run the Antora build - - Execute the fix-edit-links script - - Deploy the generated site to your hosting platform - -Example GitHub Actions workflow file (`.github/workflows/deploy.yml`): - -[source,yaml] ----- -name: Deploy Documentation - -on: - push: - branches: [ main ] - -jobs: - build: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v3 - - - name: Setup Node.js - uses: actions/setup-node@v3 - with: - node-version: '16' - - - name: Install dependencies - run: npm install -g @antora/cli @antora/site-generator-default - - - name: Build site - run: | - antora antora-assembler.yml - chmod +x ./fix-edit-links.sh - ./fix-edit-links.sh - - - name: Deploy to GitHub Pages - uses: peaceiris/actions-gh-pages@v3 - with: - github_token: ${{ secrets.GITHUB_TOKEN }} - publish_dir: ./build/site ----- +## Getting Started -### Custom Domain Configuration +Depending on your goals, choose the appropriate guide: -If you're hosting the documentation on a custom domain: +### For Contributors -1. Update the `site.url` property in `antora-assembler.yml` to match your domain -2. Configure your domain's DNS settings to point to your hosting provider -3. If using GitHub Pages, add a CNAME file to the `build/site` directory +If you want to contribute to the **documentation** or help maintain the **Antora-based documentation site**: -## GitHub Actions Workflow for Automated Deployment +📘 **Read the link:CONTRIBUTORS.adoc[Contributors Guide]** -The MicroProfile Tutorial documentation is automatically built and deployed using a GitHub Actions workflow. This section explains the workflow configuration and how it ensures continuous deployment of the documentation. +The Contributors Guide covers: -### Workflow Overview +* Setting up the Antora documentation site +* Building and running the documentation locally +* Development workflow for documentation changes +* Understanding Antora configuration +* Customizing the documentation site +* Deployment and hosting options -The repository includes a comprehensive GitHub Actions workflow (`antora.yml`) that: +### For Developers -- **Validates builds on pull requests** without deploying -- **Automatically deploys** to GitHub Pages when changes are pushed to the main branch -- **Handles concurrent deployments** to prevent conflicts -- **Ensures GitHub Pages is enabled** automatically +If you want to **download and run the source code** for the MicroProfile e-commerce application: -### Workflow Configuration +💻 **Read the link:DEVELOPERS.adoc[Developers Guide]** -The workflow is defined in `.github/workflows/build-and-deploy-tutorials.yml` and includes two main jobs: +The Developers Guide covers: -#### 1. Pull Request Validation (`validate-build`) +* How to download the source code +* Setting up your development environment +* Building and running the code for each chapter +* Understanding the project structure +* Working with individual microservices +* Common development tasks and troubleshooting -This job runs on pull requests and validates that the documentation builds correctly: +## Quick Links -- **Triggers**: Pull requests to the main branch -- **Purpose**: Validates documentation builds without deploying -- **Steps**: - * Checkout repository code - * Set up Node.js environment with npm caching - * Install Antora CLI and site generator - * Generate the site to validate build success - * Verify build output exists +### Documentation Contributors -#### 2. Build and Deploy (`build-and-deploy`) +* link:CONTRIBUTORS.adoc[Contributors Guide] - Complete guide for documentation contributors +* https://docs.antora.org/[Antora Documentation] - Official Antora documentation +* `modules/ROOT/pages/` - Documentation source files +* `antora-assembler.yml` - Main Antora configuration file -This job runs on pushes to the main branch and deploys the documentation: +### Application Developers -- **Triggers**: Pushes to main branch, manual workflow dispatch -- **Purpose**: Build and deploy documentation to GitHub Pages -- **Environment**: Uses `github-pages` environment for deployment tracking -- **Steps**: - * Checkout repository code - * Set up Node.js environment with npm caching - * Install Antora CLI and site generator - * Verify Antora installation - * Generate site using Antora with `--fetch` and `--stacktrace` options - * Configure GitHub Pages settings - * Upload generated site as artifact - * Deploy to GitHub Pages +* link:DEVELOPERS.adoc[Developers Guide] - Complete guide for application developers +* `code/` - Source code organized by chapter +* https://microprofile.io[MicroProfile] - Official MicroProfile documentation +* https://openliberty.io/guides/[Open Liberty Guides] - Additional learning resources -### Key Features +## Repository Structure -#### Concurrency Control -```yaml -concurrency: - group: "pages" - cancel-in-progress: false ``` -Prevents multiple deployments from running simultaneously while allowing in-progress deployments to complete. - -#### Automatic Pages Enablement -The workflow automatically enables GitHub Pages if it's not already configured, ensuring the repository is properly set up for deployment. - -#### Environment Protection -Uses the `github-pages` environment for deployment tracking and provides the deployment URL after successful completion. - -#### Performance Optimizations -- **npm caching**: Speeds up Node.js setup -- **Conditional deployment**: Only deploys from main branch pushes -- **Comprehensive error handling**: Includes verification steps and detailed logging - -### Required Permissions - -The workflow requires specific GitHub token permissions: - -```yaml -permissions: - id-token: write # Required for OIDC authentication to GitHub Pages - contents: read # Required to read repository contents and checkout code - pages: write # Required to deploy artifacts to GitHub Pages -``` - -### Deployment Process - -When code is pushed to the main branch: - -1. **Build Validation**: The workflow validates that Antora can successfully build the site -2. **Site Generation**: Antora processes the `antora-assembler.yml` configuration and generates the static site -3. **Pages Configuration**: GitHub Pages is automatically configured if needed -4. **Artifact Upload**: The generated site (`./build/site`) is uploaded as a deployment artifact -5. **Deployment**: The artifact is deployed to GitHub Pages - -### Accessing the Deployed Site - -After successful deployment, the documentation is available at: -``` -https://.github.io// -``` - -For the MicroProfile Tutorial, this would be: -``` -https://microprofile.github.io/microprofile-tutorial/ +microprofile-tutorial/ +├── CONTRIBUTORS.adoc # Guide for documentation contributors +├── DEVELOPERS.adoc # Guide for application developers +├── README.adoc # This file +├── code/ # Source code examples by chapter +│ ├── chapter02/ # Getting Started +│ ├── chapter03/ # Persistence and Database +│ ├── chapter04/ # Configuration +│ └── ... # Additional chapters +├── modules/ROOT/ # Antora documentation content +│ └── pages/ # Documentation pages +├── antora-assembler.yml # Antora site configuration +├── antora.yml # Component configuration +└── build/ # Generated documentation site (after build) ``` -### Monitoring Deployments - -You can monitor deployment status through: - -- **GitHub Actions tab**: View workflow runs and their status -- **Environment tab**: Track deployments to the `github-pages` environment -- **Settings > Pages**: Verify GitHub Pages configuration -- **Repository insights**: View deployment frequency and success rates - -### Troubleshooting Workflow Issues - -Common issues and solutions: - -1. **Build Failures**: - - Check the workflow logs for Antora errors - - Verify `antora-assembler.yml` configuration - - Ensure all referenced content sources are accessible - -2. **Deployment Failures**: - - Verify GitHub Pages is enabled in repository settings - - Check that the workflow has necessary permissions - - Ensure the repository has GitHub Pages configured - -3. **Content Not Updating**: - - Check if the workflow completed successfully - - Verify the build generated the expected output - - Clear browser cache to see latest changes - -### Workflow Customization - -To customize the workflow for your needs: - -1. **Change trigger conditions**: Modify the `on:` section to change when the workflow runs -2. **Update Node.js version**: Change the Node.js version in the setup step -3. **Add build steps**: Include additional processing steps before or after Antora -4. **Configure notifications**: Add steps to notify team members of deployment status - -### Migration from Static Deployment - -Previously, the repository included a `static.yml` workflow that deployed raw repository content. This has been removed in favor of the Antora-based workflow because: - -- **Proper documentation processing**: Antora generates a structured documentation site -- **Better navigation**: Antora provides proper navigation and cross-references -- **Improved maintenance**: Single workflow eliminates deployment conflicts -- **Enhanced features**: Support for themes, search, and multi-version documentation - -## Future Improvements - -Consider these potential improvements to the documentation site: - -1. **Multi-version documentation**: Configure Antora to build multiple versions of the documentation from different branches or tags -2. **Search integration**: Add a custom search engine like Algolia DocSearch -3. **Analytics**: Integrate web analytics to track usage patterns -4. **PDF generation**: Enhance the PDF export capabilities with custom styling -5. **Interactive examples**: Add interactive code examples using tools like Asciidoctor-Kroki for diagrams - -## Managing Dependencies and Updates - -### Node.js Dependencies - -The MicroProfile Tutorial documentation relies on Node.js packages, primarily Antora. These dependencies are listed in the `package.json` file. To update or manage these dependencies: - -1. **Update all dependencies**: -+ ----- -npm update ----- - -2. **Install a specific Antora version**: -+ ----- -npm install -g @antora/cli@3.1.0 @antora/site-generator-default@3.1.0 ----- - -### Understanding the UI Bundle - -The UI bundle is a critical component of an Antora site that controls the overall appearance, layout, and functionality of the documentation. It's defined in `antora-assembler.yml` under the `ui.bundle` section. - -#### Current UI Bundle Configuration - -The MicroProfile Tutorial uses a customized UI bundle from the `microprofile-documentation-ui` repository: - -[source,yaml] ----- -ui: - bundle: - url: https://github.com/microprofile/microprofile-tutorial-ui/releases/tag/latest/ui-bundle.zip - snapshot: true - supplemental_files: ./supplemental-ui ----- - -Key properties in this configuration: - -* `url`: Specifies the location of the UI bundle ZIP file -* `snapshot: true`: Tells Antora to fetch the bundle every time you build, ignoring any cached version -* `supplemental_files`: Points to a directory containing files that override or extend the UI bundle - -#### UI Bundle Components - -A standard Antora UI bundle includes: +## Prerequisites -* **CSS styles**: Controls the visual appearance of the site -* **JavaScript files**: Provides interactive functionality -* **Handlebars templates**: Defines the HTML structure of pages -* **Fonts and images**: Basic visual assets -* **Layouts**: Page structure templates for different content types +### For Documentation Work (Contributors) -#### Customizing the UI Bundle +* Node.js (for Antora) +* npm (comes with Node.js) +* Antora CLI and Site Generator -There are three approaches to customizing the UI: +See the link:CONTRIBUTORS.adoc[Contributors Guide] for detailed setup instructions. -1. **Using supplemental files** (current approach): - * Add files to the `supplemental-ui/` directory - * These files override or extend the UI bundle without modifying it - * Good for simple customizations like favicons, headers, footers, and CSS tweaks +### For Code Development (Developers) -2. **Creating a custom UI bundle**: - * Fork the default Antora UI repository - * Make extensive customizations - * Build and host your custom bundle - * Reference your custom bundle URL in `antora-assembler.yml` +* Java Development Kit (JDK) 21 or later +* Maven 3.13 or later +* Git -3. **Using a community UI bundle**: - * Several alternative UI bundles are available in the Antora ecosystem - * Each offers different features, layouts, and styling options +See the link:DEVELOPERS.adoc[Developers Guide] for detailed setup instructions. -#### Updating the UI Bundle +## Quick Start -To update to a newer version of the UI bundle: +### Building the Documentation -1. Check for new releases of the UI bundle at the GitHub repository -2. Update the URL in `antora-assembler.yml`: -+ -[source,yaml] +[source,bash] ---- -ui: - bundle: - url: https://github.com/microprofile/microprofile-tutorial-ui/releases/tag/latest/ui-bundle.zip - snapshot: true ----- - -#### Creating a Custom UI Bundle - -If you need extensive customization beyond what supplemental files allow: - -1. Fork the https://github.com/microprofile/microprofile-tutorial-ui repository -2. Make your customizations following the project's README -3. Build the UI bundle using `gulp bundle` -4. Host the resulting ZIP file (e.g., on GitHub Releases) -5. Update the `url` in `antora-assembler.yml` to point to your custom bundle +# Install Antora (first time only) +npm install -g @antora/cli @antora/site-generator-default -This approach provides the most flexibility but requires more maintenance. - -## Advanced UI Bundle Configuration - -The UI bundle configuration in Antora offers several advanced options that can enhance the documentation site's functionality and performance. - -### Bundle Cache Control - -You can control how Antora handles UI bundle caching: +# Build the documentation site +./update-repo-url.sh && antora antora-assembler.yml && ./fix-edit-links.sh -[source,yaml] ----- -ui: - bundle: - url: https://github.com/microprofile/microprofile-tutorial-ui/releases/download/latest/ui-bundle.zip - snapshot: true # Always fetch the latest version - # snapshot: false # Use cached version when available +# Run locally +cd build/site && python3 -m http.server 8080 ---- -Setting `snapshot: false` can improve build performance by using a cached version of the bundle. - -### Custom UI Bundle Features +For more details, see the link:CONTRIBUTORS.adoc[Contributors Guide]. -Modern UI bundles for Antora can include advanced features: +### Running the Code -1. **Search Integration**: Many UI bundles include built-in search functionality: -+ -[source,yaml] ----- -ui: - bundle: - url: https://github.com/microprofile/microprofile-tutorial-ui/releases/download/latest/ui-bundle.zip - supplemental_files: ./supplemental-ui -search: - engine: lunr # Or another search engine - index_latest_only: true +[source,bash] ---- +# Clone the repository +git clone https://github.com/microprofile/microprofile-tutorial.git +cd microprofile-tutorial -2. **Multiple Output Formats**: Some UI bundles support different output formats: -+ -[source,yaml] ----- -ui: - bundle: - url: https://github.com/microprofile/microprofile-tutorial-ui/releases/download/latest/ui-bundle.zip -output: - dir: ./build/site - formats: - - html - - pdf ----- +# Navigate to a chapter (e.g., Chapter 2) +cd code/chapter02/mp-ecomm-store -3. **SEO Optimizations**: Enhanced metadata for search engines: -+ -[source,yaml] ----- -site: - title: MicroProfile Tutorial - url: https://microprofile.io - keys: - seo_description: Comprehensive tutorial for learning MicroProfile - seo_keywords: microprofile, java, cloud-native, microservices ----- - -### Using a Local UI Bundle - -For development or customization, you can use a local UI bundle: - -[source,yaml] ----- -ui: - bundle: - url: ./path/to/local/ui-bundle.zip - snapshot: true +# Run in development mode +mvn liberty:dev ---- -Replease _./path/to/local/ui-bundle.zip_ with actual path to your local UI bundle under development. +For more details, see the link:DEVELOPERS.adoc[Developers Guide]. -This approach is useful when developing your own UI bundle or testing modifications. +## Contributing -### UI Bundle Development +We welcome contributions to both the documentation and the code examples! -If you decide to develop your own UI bundle: +* **Documentation Contributions**: See the link:CONTRIBUTORS.adoc[Contributors Guide] +* **Code Contributions**: See the link:DEVELOPERS.adoc[Developers Guide] -1. **Prerequisites**: Node.js and Gulp -2. **Project Structure**: - - `src/`: Source files (CSS, JavaScript, Handlebars templates) - - `gulp.d/`: Gulp tasks for building the bundle - - `preview-src/`: Sample content for testing -3. **Build Process**: - - Run `gulp bundle` to create the UI bundle - - Use `gulp preview` to test with sample content +Please ensure your contributions follow the existing patterns and include appropriate tests or validation. -### Performance Optimization Tips +## License -To optimize the performance of your documentation site: +This project is licensed under the terms specified in the link:LICENSE[LICENSE] file. -1. **Minification**: Ensure CSS and JavaScript are minified -2. **Image Optimization**: Use optimized images and consider lazy loading -3. **Font Subsetting**: Only include the character sets you need -4. **Resource Caching**: Configure proper caching headers -5. **CDN Integration**: Consider hosting assets on a CDN +## Community and Support -### Debugging UI Issues +* **MicroProfile Website**: https://microprofile.io +* **MicroProfile Google Group**: https://groups.google.com/forum/#!forum/microprofile +* **Open Liberty**: https://openliberty.io +* **Jakarta EE**: https://jakarta.ee -When troubleshooting UI problems: +## Additional Resources -1. Use browser developer tools to inspect elements and styles -2. Check the browser console for JavaScript errors -3. Verify that all required resources are loading correctly -4. Test with different browsers to identify browser-specific issues \ No newline at end of file +* https://microprofile.io[MicroProfile Official Site] +* https://openliberty.io/guides/[Open Liberty Guides] +* https://docs.antora.org/[Antora Documentation] +* https://jakarta.ee[Jakarta EE] From e36cdbf9438162eabfea4dc0f0701a270c7752b5 Mon Sep 17 00:00:00 2001 From: Tarun Telang Date: Sat, 25 Apr 2026 01:10:22 +0530 Subject: [PATCH 5/6] Create DEVELOPERS.adoc --- DEVELOPERS.adoc | 391 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 391 insertions(+) create mode 100644 DEVELOPERS.adoc diff --git a/DEVELOPERS.adoc b/DEVELOPERS.adoc new file mode 100644 index 0000000..d44a369 --- /dev/null +++ b/DEVELOPERS.adoc @@ -0,0 +1,391 @@ += MicroProfile Tutorial - Developers Guide +:toc: macro +:toc-title: Table of Contents +:toclevels: 3 +:doctype: book + +This guide provides information for developers who want to download and work with the MicroProfile e-commerce application source code. Each chapter of the tutorial includes practical code examples that demonstrate various MicroProfile features. + +toc::[] + +## Overview + +The MicroProfile Tutorial includes a comprehensive e-commerce application built with Jakarta EE 10 and MicroProfile 7.1. The application demonstrates real-world usage of MicroProfile features through a multi-service architecture including catalog, inventory, user, payment, and order services. + +## Code Organization + +The source code for the tutorial is organized by chapter in the `code/` directory. Each chapter builds upon the previous one, introducing new MicroProfile features and concepts: + +``` +code/ +├── chapter02/ # Getting Started +├── chapter03/ # Jakarta EE 10 Core Profile +├── chapter04/ # OpenAPI +├── chapter05/ # Configuration +├── chapter06/ # Health Checks +├── chapter07/ # Metrics +├── chapter08/ # Fault Tolerance +├── chapter09/ # Telemetry +├── chapter10/ # JWT Authentication +├── chapter11/ # REST Client +├── chapter12/ # Graph QL +└── chapter13/ # Reactive Messaging + +``` + +### Chapter Structure + +Each chapter directory contains one or more microservices with the following structure: + +``` +chapterXX/ +├── / +│ ├── src/ +│ │ ├── main/ +│ │ │ ├── java/ # Java source code +│ │ │ ├── liberty/config/ # Open Liberty configuration +│ │ │ └── resources/ # Application resources +│ │ └── test/ # Unit and integration tests +│ ├── pom.xml # Maven build configuration +│ └── README.adoc # Service-specific documentation +``` + +## Getting Started + +### Prerequisites + +Before working with the code, ensure you have the following installed: + +#### Required Software + +* **Java Development Kit (JDK) 21 or later** +* **Maven 3.9.12 or later** - For building the applications +* **Git** - For cloning the repository + +#### Development Environment Setup + +We recommend using SDKMAN for managing Java versions, as it makes it easy to switch between different JDK versions. + +##### Installing SDKMAN + +If SDKMAN is not already installed, follow the official instructions at https://sdkman.io/install/ or run: + +[source,bash] +---- +curl -s "https://get.sdkman.io" | bash +source "$HOME/.sdkman/bin/sdkman-init.sh" +---- + +##### Installing and Managing Java with SDKMAN + +[source,bash] +---- +# List available Java versions +sdk list java + +# Install JDK 17 (Microsoft build) +sdk install java 17.0.15-ms + +# List installed Java versions +sdk list java | grep -E ".*\s+installed" + +# Switch to JDK 17 for the current shell session +sdk use java 17.0.15-ms + +# Make JDK 17 the default for all sessions +sdk default java 17.0.15-ms + +# Verify the current Java version +java -version +---- + +##### Recommended IDEs and Extensions + +**Visual Studio Code:** + +* Java Extension Pack +* Language Support for Java by Red Hat +* Liberty Tools for VS Code +* AsciiDoc extension (for viewing documentation) + +**IntelliJ IDEA:** + +* Built-in Java and Maven support +* MicroProfile plugin (available in the marketplace) +* Liberty plugin (available in the marketplace) + +**Eclipse:** + +* Eclipse IDE for Enterprise Java and Web Developers +* Liberty Developer Tools + +## Downloading the Source Code + +### Clone the Repository + +To get all the code for the tutorial: + +[source,bash] +---- +git clone https://github.com/microprofile/microprofile-tutorial.git +cd microprofile-tutorial +---- + +### Navigate to a Specific Chapter + +[source,bash] +---- +# For example, to work with Chapter 3 code +cd code/chapter03/catalog +---- + +## Building and Running the Code + +The tutorial applications use Maven and the Open Liberty Maven plugin for building and running. + +### Building an Application + +To build any microservice, navigate to its directory and run: + +[source,bash] +---- +mvn clean package +---- + +This command: +- Compiles the Java source code +- Runs unit tests +- Packages the application as a WAR file + +### Running an Application + +The easiest way to run an application is using the Liberty Maven plugin in development mode: + +[source,bash] +---- +mvn liberty:dev +---- + +**Development mode features:** +- Automatically rebuilds and redeploys on code changes +- Runs tests on demand by pressing Enter +- Supports hot reload for faster development +- Provides debugging capabilities + +To exit development mode, press `Ctrl+C` or type `q` and press Enter. + +### Accessing the Application + +Once the server is running, you can access the application endpoints. The default configuration typically uses: + +* **Host**: localhost (or your system hostname) +* **Port**: Varies by service (commonly 5050, 5051, 5052, etc.) + +For example, for the catalog service in Chapter 3: +``` +http://localhost:5050/catalog/api/products +``` + +Replace `localhost` with your system hostname if accessing from a different machine. + +### Running Tests + +To run the unit and integration tests: + +[source,bash] +---- +# Run all tests +mvn test + +# Run a specific test class +mvn test -Dtest=YourTestClassName +---- + +## Working with Individual Chapters + +Each chapter introduces specific MicroProfile features. + +## Common Development Tasks + +### Changing Server Ports + +If you need to run multiple services simultaneously or avoid port conflicts, you can change the HTTP port in the Liberty server configuration. + +Edit `src/main/liberty/config/server.xml`: + +[source,xml] +---- + + httpsPort="9443" /> +---- + +### Configuring the Database + +Most chapters use Derby embedded database for simplicity. The database configuration is in `src/main/resources/META-INF/persistence.xml`: + +[source,xml] +---- + + jdbc/DefaultDataSource + + + + +---- + +### Adding Dependencies + +To add new dependencies, edit the `pom.xml` file. The tutorial uses Maven for dependency management: + +[source,xml] +---- + + + + org.example + example-library + 1.0.0 + + +---- + +## Technology Stack + +The MicroProfile Tutorial applications use the following technology stack: + +### Core Technologies + +* **Jakarta EE 10** - Enterprise Java specifications +* **MicroProfile 6.1** - Cloud-native microservices specifications +* **Maven** - Build and dependency management + +### Jakarta EE APIs Used + +* **Jakarta RESTful Web Services (JAX-RS)** - REST API development +* **Jakarta Persistence (JPA)** - Database persistence +* **Jakarta Contexts and Dependency Injection (CDI)** - Dependency injection +* **Jakarta Bean Validation** - Input validation +* **Jakarta JSON Binding (JSON-B)** - JSON serialization +* **Jakarta JSON Processing (JSON-P)** - JSON processing + +### MicroProfile APIs Used + +* **MicroProfile Config** - Configuration management +* **MicroProfile Health** - Health check endpoints +* **MicroProfile Metrics** - Application metrics +* **MicroProfile OpenAPI** - API documentation +* **MicroProfile JWT** - JWT authentication +* **MicroProfile Fault Tolerance** - Resilience patterns +* **MicroProfile REST Client** - Type-safe REST clients +* **MicroProfile GraphQL** - GraphQL based calls +* * **MicroProfile Reactive Messaging** - Event Driven Architecture and Reactive Messaging using Asynchronous calls + +### Additional Libraries + +* **Lombok** - Reduces boilerplate code with annotations +* **JUnit 5** - Unit testing framework +* **Derby** - Embedded database (for development) + +## Best Practices + +When working with the tutorial code, consider these best practices: + +### Development Workflow + +1. **Start with Early Chapters**: If you're new to MicroProfile, start with Chapter 2 and progress sequentially. +2. **Read the Documentation**: Each service includes a README.adoc with specific instructions and explanations. +3. **Experiment**: The code is designed for learning - modify it, break it, and understand how it works. + +### Code Organization + +1. **Follow the Layered Architecture**: The code uses a clear separation between resources, services, repositories, and entities. +2. **Keep Services Small**: Each microservice focuses on a specific business capability. +3. **Use DTOs When Appropriate**: Don't expose entity classes directly in REST APIs for complex scenarios. + +### Testing + +1. **Write Tests**: Add unit tests for your changes to ensure they work correctly. +2. **Test in Development Mode**: Use the interactive testing feature in `mvn liberty:dev` by pressing Enter. +3. **Integration Tests**: Some chapters include integration tests that verify end-to-end functionality. + +### Configuration + +1. **Externalize Configuration**: Use MicroProfile Config for values that might change between environments. +2. **Use Profiles**: Configure different settings for development, testing, and production. +3. **Document Configuration**: Keep track of required configuration properties. + +## Troubleshooting + +### Common Issues and Solutions + +#### Port Already in Use + +**Problem**: Error message indicates the port is already in use. + +**Solution**: +```bash +# Find process using the port (e.g., 5050) +lsof -i :5050 + +# Kill the process +kill + +# Or change the port in server.xml +``` + +#### Maven Build Failures + +**Problem**: Maven fails to download dependencies or build the project. + +**Solution**: +```bash +# Clean Maven cache and rebuild +mvn clean install -U + +# Verify Maven is properly configured +mvn -version + +# Check your internet connection and proxy settings if behind a firewall +``` + +#### Database Connection Errors + +**Problem**: Application cannot connect to the database. + +**Solution**: +- Verify the database configuration in `persistence.xml` +- Check that Derby is included in dependencies +- Look for database lock files that might need deletion +- Review server logs for detailed error messages + +## Next Steps + +After setting up your development environment and exploring the code: + +1. **Run the Examples**: Start with Chapter 2 and work through each chapter sequentially +2. **Modify the Code**: Try adding new features or changing existing functionality +3. **Build Your Own Service**: Create a new microservice using the patterns learned +4. **Integrate Services**: Practice calling one service from another using REST Client +5. **Deploy to Production**: Learn about deploying MicroProfile applications to cloud platforms + +## Additional Resources + +### Official Documentation + +* **MicroProfile**: https://microprofile.io +* **Jakarta EE**: https://jakarta.ee + +## Contributing + +If you find issues with the code or have suggestions for improvements: + +1. Check existing issues in the GitHub repository +2. Create a new issue with: + - Clear description of the problem or suggestion + - Steps to reproduce (for bugs) + - Expected vs. actual behavior +3. Consider submitting a pull request with fixes or enhancements + +For documentation improvements, see the link:CONTRIBUTORS.adoc[Contributors Guide]. From 2f0d77ff497503c53f653d312cfa01dc28ae198d Mon Sep 17 00:00:00 2001 From: Tarun Telang Date: Sat, 25 Apr 2026 01:14:23 +0530 Subject: [PATCH 6/6] Create CONTRIBUTORS.adoc --- CONTRIBUTORS.adoc | 1034 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 1034 insertions(+) create mode 100644 CONTRIBUTORS.adoc diff --git a/CONTRIBUTORS.adoc b/CONTRIBUTORS.adoc new file mode 100644 index 0000000..a706b03 --- /dev/null +++ b/CONTRIBUTORS.adoc @@ -0,0 +1,1034 @@ += MicroProfile Tutorial - Contributors Guide +:toc: macro +:toc-title: Table of Contents +:toclevels: 3 +:doctype: book + +This guide provides information for contributors to the MicroProfile Tutorial documentation. Learn how to set up, build, and customize the documentation site built with https://antora.org/[Antora]. + +toc::[] + +## Prerequisites + +### Install Antora +You need to https://docs.antora.org/antora/latest/install-and-run-quickstart/#install-antora[install Antora] using npm. If you don't have Node.js installed, you can https://docs.antora.org/antora/latest/install-and-run-quickstart/#install-nodejs[install Node.js] by following this instructions. + +``` +npm install -g @antora/cli @antora/site-generator-default +``` + +### Recommended VS Code Extensions + +For the best experience editing AsciiDoc files in Visual Studio Code, we recommend installing the following extensions: + +* AsciiDoc extension by Asciidoctor (`asciidoctor.asciidoctor-vscode`) - Provides rich language support for AsciiDoc +* Auto Open Preview Panel (`matt-rudge.auto-open-preview-panel`) - Opens preview automatically when opening AsciiDoc files + +## Building the Documentation Site + +You can build the site by running the following commands in the root directory of the project: + +``` +./update-repo-url.sh +antora antora-assembler.yml +./fix-edit-links.sh +``` + +- The first command ensures that the repository URLs are up-to-date. +- The second command will generate the site in the `build/site` directory. +- The third command fixes the "Edit this Page" links to properly point to GitHub instead of local file paths. + +Alternatively, you can use the following one-liner: + +``` +./update-repo-url.sh && antora antora-assembler.yml && ./fix-edit-links.sh +``` + +## Running the Site Locally + +You can run the site locally using Python's built-in HTTP server. First, navigate to the `build/site` directory: +``` +cd build/site +``` +Then, run the following command: +``` +python3 -m http.server 8080 +``` +This will start a local server on port 8080. You can then open your web browser and navigate to `http://:8080` to view the site. + +[TIP] +==== +If port 8080 is already in use, you can free it by finding and stopping the process using it. For example, on Linux or macOS: ++ +---- +lsof -i :8080 +kill +---- +Replace `` with the process ID shown in the output. +==== + +## Cleaning Up Build Artifacts + +Over time, the `build/` directory can accumulate files and may consume significant disk space. You may also want to clean up the build when switching between branches or before deploying a fresh build. + +### Removing Build Artifacts + +To remove all build artifacts, run: + +```bash +rm -rf build +``` + +This removes the entire `build/` directory including: +- `build/site/` - The generated HTML documentation site +- `build/assembler/` - Temporary Antora processing files +- All PDFs and other generated assets + +### Selective Cleanup + +If you want to keep certain files (such as generated PDFs for archival), you can remove just the site: + +```bash +rm -rf build/site +``` + +Or keep only the site and remove intermediate files: + +```bash +rm -rf build/assembler +``` + +### When to Clean Up + +- **Before a fresh build**: Run `rm -rf build` before rebuilding to ensure a clean state +- **When switching branches**: Clean up after switching to a different version branch +- **To free disk space**: Remove old builds if disk space is limited +- **Before deployment**: Ensure you're deploying a fresh build with no stale files + +### Automated Cleanup During Build + +You can combine cleanup with the build command for a fresh build: + +```bash +rm -rf build && antora antora-assembler.yml && ./fix-edit-links.sh +``` + +Or as a one-liner with the complete build process: + +```bash +rm -rf build && ./update-repo-url.sh && antora antora-assembler.yml && ./fix-edit-links.sh +``` + +## Development Workflow + +To streamline the development process, a development server script is included that can automatically rebuild the documentation when files change. + +### Using the Development Server + +The `dev-server.sh` script provides three commands: + +1. **Build only**: ++ +---- +./dev-server.sh build +---- ++ +This builds the documentation site once. + +2. **Build and serve**: ++ +---- +./dev-server.sh serve +---- ++ +This builds the documentation site and starts a local HTTP server on port 8080. + +3. **Build, serve, and watch for changes**: ++ +---- +./dev-server.sh watch +---- ++ +This builds the documentation site, starts a local HTTP server, and automatically rebuilds the site when files change. + +### Requirements + +The development server requires: + +- Python 3 (for the HTTP server) +- inotify-tools (for file watching, will be automatically installed if missing) + +### Typical Development Workflow + +1. Start the development server in watch mode: `./dev-server.sh watch` +2. Open your browser at http://localhost:8080 +3. Edit AsciiDoc files in the `modules/ROOT/pages/` directory +4. Save your changes and see them automatically reflected in the browser + +## Understanding Antora Configuration + +Antora uses several configuration files to manage the documentation site. The main files are: + +- `antora-assembler.yml`: The primary configuration file that defines the site structure, UI bundle, and supplemental files. +- `antora.yml`: Component configuration for the MicroProfile Tutorial, including metadata and edit URL configuration. +- `supplemental-ui/`: Directory containing customizations like favicons and custom partials. + +### Site Structure Configuration + +The main configuration file for the site is `antora-assembler.yml`, which defines: + +- **Site metadata**: Title, URL, and starting page +- **Content sources**: Where to find documentation content +- **UI bundle**: The theme and UI components to use +- **Output**: Where to generate the site +- **Asciidoc attributes**: Global attributes for all pages + +Here's a breakdown of the key sections: + +#### Site Information +[source,yaml] +---- +site: + title: MicroProfile Tutorial + url: https://microprofile.io + start_page: microprofile-tutorial::index.adoc + keys: + show_edit_page_link: true +---- + +#### Content Sources +[source,yaml] +---- +content: + sources: + - url: . + start_path: . + branches: HEAD +---- + +#### UI Configuration +[source,yaml] +---- +ui: + bundle: + url: https://github.com/microprofile/microprofile-tutorial-ui/releases/download/latest/ui-bundle.zip + snapshot: true + supplemental_files: ./supplemental-ui +---- + +### Component Configuration + +The `antora.yml` file defines the documentation component: + +[source,yaml] +---- +name: microprofile-tutorial +title: MicroProfile Tutorial +version: 6.1 +edit_url: https://github.com/microprofile/microprofile-tutorial/tree/main/modules/ROOT/pages/{path} +asciidoc: + attributes: + source-language: asciidoc@ + table-caption: false + xrefstyle: full +nav: + - modules/ROOT/pages/nav.adoc +start_page: index.adoc +---- + +Key properties: + +- **name**: The component name used in xrefs and URLs +- **title**: The human-readable title +- **version**: The component version (appears in URLs and version selector) +- **edit_url**: The URL template for "Edit this Page" links +- **nav**: The navigation file(s) for the component +- **start_page**: The default page when accessing the component root + +### Navigation Configuration + +The navigation is defined in `modules/ROOT/pages/nav.adoc` and uses AsciiDoc with special Antora directives: + +[source,asciidoc] +---- +* xref:index.adoc[Home] +* xref:chapter01/chapter01.adoc[Chapter 1: Introduction] +* Chapter 2: Getting Started +** xref:chapter02/chapter02-01.adoc[Section 2.1: Environment Setup] +---- + +The navigation structure directly affects the sidebar menu in the generated site. + +## Navigation and Site Structure + +The navigation system in Antora is a critical component that determines how users find and access content. Understanding how navigation works can help you create a better user experience. + +### Navigation Components + +The MicroProfile Tutorial site navigation consists of: + +1. **Main Navigation**: Defined in `modules/ROOT/pages/nav.adoc`, controls the sidebar navigation. +2. **Breadcrumbs**: Shows the current page's location in the content hierarchy. +3. **Previous/Next Links**: Helps users navigate sequentially through content. +4. **Table of Contents**: Generated from page headings, provides in-page navigation. + +### Customizing Navigation + +The navigation can be customized in several ways: + +#### Modifying the nav.adoc File + +The main navigation structure is defined in `modules/ROOT/pages/nav.adoc`: + +[source,asciidoc] +---- +* xref:index.adoc[Home] +* xref:chapter01/chapter01.adoc[Chapter 1: Introduction] +* Chapter 2: Getting Started +** xref:chapter02/chapter02-01.adoc[Section 2.1: Environment Setup] +** xref:chapter02/chapter02-02.adoc[Section 2.2: First Steps] +---- + +Navigation entries can be: + +- Direct links to pages (with `xref:`) +- Unlinked category headers (without `xref:`) +- Nested to create hierarchical structures (using multiple `*` characters) + +#### Navigation UI Customization + +To customize the navigation appearance: + +1. **Style Overrides**: Add CSS for navigation elements in your supplemental UI files. +2. **Template Customization**: Override the navigation templates in the UI bundle. +3. **JavaScript Enhancements**: Add interactive features like search, filtering, or collapsible sections. + +Example CSS customization for navigation: + +[source,css] +---- +/* Customizing the sidebar navigation */ +.nav-menu { + background-color: #f5f5f5; +} + +.nav-item.is-current-page > .nav-link { + color: #0d5aa7; + font-weight: bold; +} +---- + +### Navigation Best Practices + +1. **Logical Organization**: Group related content together in the navigation. +2. **Consistent Naming**: Use consistent naming conventions for pages and sections. +3. **Limited Nesting**: Avoid deep nesting (more than 3 levels) to prevent navigation complexity. +4. **Descriptive Labels**: Use clear, descriptive labels for navigation items. +5. **Progressive Disclosure**: Organize content from basic to advanced topics. + +### Advanced Navigation Features + +The UI bundle can be customized to include advanced navigation features: + +1. **Search Integration**: Add search functionality to help users find content quickly. +2. **Version Selector**: Allow users to switch between different versions of the documentation. +3. **Component Selector**: If you have multiple components, provide a way to navigate between them. +4. **Tag-Based Navigation**: Group content by tags or categories for alternative navigation paths. + +## About the fix-edit-links.sh Script + +The `fix-edit-links.sh` script is a necessary post-processing step in the build process. Despite having `edit_url` properly configured in `antora.yml`, when building from a local repository (`url: .` in `antora-assembler.yml`), Antora generates edit links that point to local file paths instead of GitHub URLs. + +The script performs a simple text replacement in the generated HTML files, replacing local file paths with proper GitHub repository URLs. This ensures that the "Edit this Page" links work correctly for users viewing the documentation. + +If you update the repository URL or branch name, make sure to update the replacement URL in the `fix-edit-links.sh` script accordingly. The current implementation assumes the GitHub repository URL is `https://github.com/microprofile/microprofile-tutorial` and the branch is `main`. + +## Automating Repository URL Configuration + +To simplify the management of repository URLs across configuration files, the `update-repo-url.sh` script is provided. This script: + +1. Automatically detects your Git repository URL and current branch +2. Updates the `edit_url` in `antora.yml` +3. Updates the repository information in `fix-edit-links.sh` + +### Using the URL Configuration Script + +Run the script before building the documentation: + +``` +./update-repo-url.sh +``` + +This ensures that both the Antora configuration and the fix-edit-links script use the same repository URL and branch, eliminating duplication and reducing the chance of errors. + +When you clone the repository or switch branches, run this script to update the configuration automatically. + +## Multi-Version Documentation Consistency + +When maintaining multiple versions of the documentation (e.g., 6.1 and 7.1), certain configuration files must remain consistent across all branches to ensure proper version selection and navigation. + +### Critical Consistency Requirements + +The following configuration **must be identical across all branches** (`main`, `6.1`, `7.1`, etc.): + +#### 1. Antora Assembler Configuration + +The `antora-assembler.yml` file must specify **all** versions in the `branches` array: + +[source,yaml] +---- +content: + sources: + - url: https://github.com/microprofile/microprofile-tutorial.git + branches: [6.1, main] # List all version branches here + start_path: / +---- + +**Important**: This configuration should be identical on every branch. Even when working on the `6.1` branch, the `antora-assembler.yml` file should still reference both `6.1` and `7.1` branches. + +**Reason**: This ensures that the version dropdown selector displays all available versions regardless of which version is currently selected. Users viewing version 6.1 need to see version 7.1 available in the dropdown, and vice versa. + +#### 2. Branch-Specific Antora Component Configuration + +The `antora.yml` file defines the version and should be **different on each branch**: + +[source,yaml] +---- +# On the 6.1 branch +name: microprofile-tutorial +version: 6.1 +edit_url: https://github.com/microprofile/microprofile-tutorial/tree/6.1/modules/ROOT/pages/{path} + +# On the main branch +name: microprofile-tutorial +version: 7.1 +edit_url: https://github.com/microprofile/microprofile-tutorial/tree/main/modules/ROOT/pages/{path} +---- + +**Reason**: Each branch represents a different version, so the version number and edit URL should reflect which branch it is. + +### Maintaining Consistency + +#### When Adding a New Version + +If you plan to add a new version (e.g., version 8.0): + +1. Create the new version branch (e.g., `v8.0`) +2. Create the corresponding `antora.yml` with `version: 8.0` +3. Update `antora-assembler.yml` on **all existing branches** to include the new version: ++ +[source,yaml] +---- +branches: [6.1, 7.1, 8.0] # Add the new version +---- +4. Update the same configuration through a pull request or by updating each branch + +#### When Deprecating a Version + +If you need to remove an older version: + +1. Remove it from the `branches` array in `antora-assembler.yml` on **all branches** +2. Optionally keep the branch in Git for historical reference, but exclude it from Antora builds + +#### Verification Steps + +After updating configurations: + +1. Rebuild the site: `npm run build` or `antora antora-assembler.yml` +2. Verify that the version dropdown shows all expected versions +3. Test switching between versions to ensure cross-version navigation works +4. Commit and push changes to all affected branches + +### Troubleshooting Version Selection Issues + +**Problem**: When viewing version 6.1, the version dropdown only shows 6.1 (version 7.1 is missing) + +**Solution**: Verify that `antora-assembler.yml` on the 6.1 branch includes both versions: +```yaml +branches: [6.1, main] +``` + +**Problem**: Version dropdown is not appearing at all + +**Solution**: +- Ensure the UI bundle supports version selection (check `ui.bundle.url`) +- Verify that `antora-assembler.yml` specifies multiple branches +- Confirm both versions have proper `antora.yml` files with different version numbers + +## Customizing the Documentation Site + +The MicroProfile Tutorial documentation site can be customized in various ways to enhance its appearance and functionality. Here are the key customization options: + +### Favicon Configuration + +Favicons are configured using the `supplemental-ui/partials/head-meta.hbs` file, which is included in the HTML `` section of each page. The current setup includes: + +- An SVG favicon (primary) +- A PNG favicon (fallback for browsers that don't support SVG) + +To change the favicons: + +1. Replace the files in `supplemental-ui/img/`: + - `favicon.svg` - Vector version of the favicon + - `favicon.png` - Bitmap version of the favicon +2. Make sure the references in `head-meta.hbs` match your file names + +### UI Customization + +The UI bundle is defined in `antora-assembler.yml` under the `ui.bundle.url` key. The current configuration uses a custom UI bundle from the `microprofile-documentation-ui` repository. + +To apply additional customizations: + +1. Add or modify files in the `supplemental-ui/` directory: + - `partials/` - Override specific UI components + - `css/` - Add custom CSS styles + - `js/` - Add custom JavaScript + +Common customizations include: + +- Header and footer modifications +- Custom CSS for branding +- Additional JavaScript functionality + +### Edit Page Links + +Edit page links are configured in two places: + +1. `antora.yml` - The `edit_url` property defines the base URL for edit links +2. `antora-assembler.yml` - The `site.keys.show_edit_page_link` property enables the display of edit links + +If you change the repository URL or branch, update both: +- The `edit_url` in `antora.yml` +- The replacement URL in `fix-edit-links.sh` + +### Redirection Configuration + +The project includes a `redirect.html` file that automatically redirects users from the root URL to the latest version of the documentation. This is particularly useful when hosting the documentation on GitHub Pages or other static hosting services. + +The redirect is configured to: +- Use relative URLs for maximum compatibility +- Fall back to JavaScript-based redirection if needed + +### Further Customization Resources + +For more advanced customization options, refer to the Antora documentation: + +- [Antora UI Documentation](https://docs.antora.org/antora-ui-default/) +- [Customizing the UI](https://docs.antora.org/antora/latest/playbook/ui-supplemental-files/) +- [Page Templates](https://docs.antora.org/antora/latest/templates/) + +## Contributing to the Documentation + +### Directory Structure + +The MicroProfile Tutorial follows the standard Antora directory structure: + +- `modules/ROOT/pages/` - Contains the main documentation content in AsciiDoc format +- `modules/ROOT/assets/images/` - Contains images used in the documentation + +### AsciiDoc Best Practices + +When contributing to the documentation, follow these AsciiDoc best practices: + +1. Use proper heading levels (start with `==` for top-level headings within a page) +2. Use cross-references to link between pages (`xref:page-id.adoc[]`) +3. Add proper metadata to each page: ++ +---- += Page Title +:page-id: unique-id +---- ++ +4. For code examples, use proper language specifiers: ++ +---- +[source,java] +---- +// Java code here +---- +---- + +### Adding New Content + +To add new content to the documentation: + +1. Create a new `.adoc` file in the appropriate directory under `modules/ROOT/pages/` +2. Add a reference to the new page in the navigation file (`modules/ROOT/pages/nav.adoc`) +3. Build the site to verify your changes + +### Handling Images + +When adding images to the documentation: + +1. Place image files in the `modules/ROOT/images/` directory +2. Reference images using the `image::` directive: ++ +---- +image::image-name.png[Alt text for the image, width=600] +---- + +## Troubleshooting + +### Common Build Issues + +1. **Missing dependencies** + ``` + npm install -g @antora/cli @antora/site-generator-default + ``` + +2. **Edit links not working** + - Make sure `fix-edit-links.sh` is executable: `chmod +x fix-edit-links.sh` + - Verify the GitHub repository URL and branch in both `antora.yml` and `fix-edit-links.sh` + +3. **Incorrect links in navigation** + - Check that page references in `nav.adoc` use proper xref syntax + - Verify that page IDs are unique across the documentation + +### Getting Help + +If you encounter issues not covered in this documentation, check the following resources: + +- [Antora Documentation](https://docs.antora.org/) +- [AsciiDoc Syntax Quick Reference](https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/) + +## Hosting and Deployment + +The MicroProfile Tutorial documentation site is designed to be deployed as static HTML, which can be hosted on various platforms. Here are some common hosting options and deployment methods: + +### GitHub Pages + +GitHub Pages is a simple and free hosting option for static sites: + +1. Build the site: `antora antora-assembler.yml && ./fix-edit-links.sh` +2. Copy the contents of the `build/site` directory to your GitHub Pages branch (typically `gh-pages`) +3. Configure GitHub repository settings to enable GitHub Pages + +The `redirect.html` file can be renamed to `index.html` at the repository root to automatically redirect visitors to the latest documentation version. + +### Static Web Hosting + +Any static web hosting service can host the documentation: + +1. Build the site: `antora antora-assembler.yml && ./fix-edit-links.sh` +2. Upload the contents of the `build/site` directory to your web server +3. Configure your web server to serve `index.html` as the default document + +### Continuous Integration + +To automate the build and deployment process, you can use GitHub Actions or another CI/CD system: + +1. Set up a workflow that triggers on pushes to the main branch +2. Configure the workflow to: + - Install Node.js and required dependencies + - Run the Antora build + - Execute the fix-edit-links script + - Deploy the generated site to your hosting platform + +Example GitHub Actions workflow file (`.github/workflows/deploy.yml`): + +[source,yaml] +---- +name: Deploy Documentation + +on: + push: + branches: [ main ] + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v3 + + - name: Setup Node.js + uses: actions/setup-node@v3 + with: + node-version: '16' + + - name: Install dependencies + run: npm install -g @antora/cli @antora/site-generator-default + + - name: Build site + run: | + antora antora-assembler.yml + chmod +x ./fix-edit-links.sh + ./fix-edit-links.sh + + - name: Deploy to GitHub Pages + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./build/site +---- + +### Custom Domain Configuration + +If you're hosting the documentation on a custom domain: + +1. Update the `site.url` property in `antora-assembler.yml` to match your domain +2. Configure your domain's DNS settings to point to your hosting provider +3. If using GitHub Pages, add a CNAME file to the `build/site` directory + +## GitHub Actions Workflow for Automated Deployment + +The MicroProfile Tutorial documentation is automatically built and deployed using a GitHub Actions workflow. This section explains the workflow configuration and how it ensures continuous deployment of the documentation. + +### Workflow Overview + +The repository includes a comprehensive GitHub Actions workflow (`antora.yml`) that: + +- **Validates builds on pull requests** without deploying +- **Automatically deploys** to GitHub Pages when changes are pushed to the main branch +- **Handles concurrent deployments** to prevent conflicts +- **Ensures GitHub Pages is enabled** automatically + +### Workflow Configuration + +The workflow is defined in `.github/workflows/build-and-deploy-tutorials.yml` and includes two main jobs: + +#### 1. Pull Request Validation (`validate-build`) + +This job runs on pull requests and validates that the documentation builds correctly: + +- **Triggers**: Pull requests to the main branch +- **Purpose**: Validates documentation builds without deploying +- **Steps**: + * Checkout repository code + * Set up Node.js environment with npm caching + * Install Antora CLI and site generator + * Generate the site to validate build success + * Verify build output exists + +#### 2. Build and Deploy (`build-and-deploy`) + +This job runs on pushes to the main branch and deploys the documentation: + +- **Triggers**: Pushes to main branch, manual workflow dispatch +- **Purpose**: Build and deploy documentation to GitHub Pages +- **Environment**: Uses `github-pages` environment for deployment tracking +- **Steps**: + * Checkout repository code + * Set up Node.js environment with npm caching + * Install Antora CLI and site generator + * Verify Antora installation + * Generate site using Antora with `--fetch` and `--stacktrace` options + * Configure GitHub Pages settings + * Upload generated site as artifact + * Deploy to GitHub Pages + +### Key Features + +#### Concurrency Control +```yaml +concurrency: + group: "pages" + cancel-in-progress: false +``` +Prevents multiple deployments from running simultaneously while allowing in-progress deployments to complete. + +#### Automatic Pages Enablement +The workflow automatically enables GitHub Pages if it's not already configured, ensuring the repository is properly set up for deployment. + +#### Environment Protection +Uses the `github-pages` environment for deployment tracking and provides the deployment URL after successful completion. + +#### Performance Optimizations +- **npm caching**: Speeds up Node.js setup +- **Conditional deployment**: Only deploys from main branch pushes +- **Comprehensive error handling**: Includes verification steps and detailed logging + +### Required Permissions + +The workflow requires specific GitHub token permissions: + +```yaml +permissions: + id-token: write # Required for OIDC authentication to GitHub Pages + contents: read # Required to read repository contents and checkout code + pages: write # Required to deploy artifacts to GitHub Pages +``` + +### Deployment Process + +When code is pushed to the main branch: + +1. **Build Validation**: The workflow validates that Antora can successfully build the site +2. **Site Generation**: Antora processes the `antora-assembler.yml` configuration and generates the static site +3. **Pages Configuration**: GitHub Pages is automatically configured if needed +4. **Artifact Upload**: The generated site (`./build/site`) is uploaded as a deployment artifact +5. **Deployment**: The artifact is deployed to GitHub Pages + +### Accessing the Deployed Site + +After successful deployment, the documentation is available at: +``` +https://.github.io// +``` + +For the MicroProfile Tutorial, this would be: +``` +https://microprofile.github.io/microprofile-tutorial/ +``` + +### Monitoring Deployments + +You can monitor deployment status through: + +- **GitHub Actions tab**: View workflow runs and their status +- **Environment tab**: Track deployments to the `github-pages` environment +- **Settings > Pages**: Verify GitHub Pages configuration +- **Repository insights**: View deployment frequency and success rates + +### Troubleshooting Workflow Issues + +Common issues and solutions: + +1. **Build Failures**: + - Check the workflow logs for Antora errors + - Verify `antora-assembler.yml` configuration + - Ensure all referenced content sources are accessible + +2. **Deployment Failures**: + - Verify GitHub Pages is enabled in repository settings + - Check that the workflow has necessary permissions + - Ensure the repository has GitHub Pages configured + +3. **Content Not Updating**: + - Check if the workflow completed successfully + - Verify the build generated the expected output + - Clear browser cache to see latest changes + +### Workflow Customization + +To customize the workflow for your needs: + +1. **Change trigger conditions**: Modify the `on:` section to change when the workflow runs +2. **Update Node.js version**: Change the Node.js version in the setup step +3. **Add build steps**: Include additional processing steps before or after Antora +4. **Configure notifications**: Add steps to notify team members of deployment status + +### Migration from Static Deployment + +Previously, the repository included a `static.yml` workflow that deployed raw repository content. This has been removed in favor of the Antora-based workflow because: + +- **Proper documentation processing**: Antora generates a structured documentation site +- **Better navigation**: Antora provides proper navigation and cross-references +- **Improved maintenance**: Single workflow eliminates deployment conflicts +- **Enhanced features**: Support for themes, search, and multi-version documentation + +## Future Improvements + +Consider these potential improvements to the documentation site: + +1. **Multi-version documentation**: Configure Antora to build multiple versions of the documentation from different branches or tags +2. **Search integration**: Add a custom search engine like Algolia DocSearch +3. **Analytics**: Integrate web analytics to track usage patterns +4. **PDF generation**: Enhance the PDF export capabilities with custom styling +5. **Interactive examples**: Add interactive code examples using tools like Asciidoctor-Kroki for diagrams + +## Managing Dependencies and Updates + +### Node.js Dependencies + +The MicroProfile Tutorial documentation relies on Node.js packages, primarily Antora. These dependencies are listed in the `package.json` file. To update or manage these dependencies: + +1. **Update all dependencies**: ++ +---- +npm update +---- + +2. **Install a specific Antora version**: ++ +---- +npm install -g @antora/cli@3.1.0 @antora/site-generator-default@3.1.0 +---- + +### Understanding the UI Bundle + +The UI bundle is a critical component of an Antora site that controls the overall appearance, layout, and functionality of the documentation. It's defined in `antora-assembler.yml` under the `ui.bundle` section. + +#### Current UI Bundle Configuration + +The MicroProfile Tutorial uses a customized UI bundle from the `microprofile-documentation-ui` repository: + +[source,yaml] +---- +ui: + bundle: + url: https://github.com/microprofile/microprofile-tutorial-ui/releases/tag/latest/ui-bundle.zip + snapshot: true + supplemental_files: ./supplemental-ui +---- + +Key properties in this configuration: + +* `url`: Specifies the location of the UI bundle ZIP file +* `snapshot: true`: Tells Antora to fetch the bundle every time you build, ignoring any cached version +* `supplemental_files`: Points to a directory containing files that override or extend the UI bundle + +#### UI Bundle Components + +A standard Antora UI bundle includes: + +* **CSS styles**: Controls the visual appearance of the site +* **JavaScript files**: Provides interactive functionality +* **Handlebars templates**: Defines the HTML structure of pages +* **Fonts and images**: Basic visual assets +* **Layouts**: Page structure templates for different content types + +#### Customizing the UI Bundle + +There are three approaches to customizing the UI: + +1. **Using supplemental files** (current approach): + * Add files to the `supplemental-ui/` directory + * These files override or extend the UI bundle without modifying it + * Good for simple customizations like favicons, headers, footers, and CSS tweaks + +2. **Creating a custom UI bundle**: + * Fork the default Antora UI repository + * Make extensive customizations + * Build and host your custom bundle + * Reference your custom bundle URL in `antora-assembler.yml` + +3. **Using a community UI bundle**: + * Several alternative UI bundles are available in the Antora ecosystem + * Each offers different features, layouts, and styling options + +#### Updating the UI Bundle + +To update to a newer version of the UI bundle: + +1. Check for new releases of the UI bundle at the GitHub repository +2. Update the URL in `antora-assembler.yml`: ++ +[source,yaml] +---- +ui: + bundle: + url: https://github.com/microprofile/microprofile-tutorial-ui/releases/tag/latest/ui-bundle.zip + snapshot: true +---- + +#### Creating a Custom UI Bundle + +If you need extensive customization beyond what supplemental files allow: + +1. Fork the https://github.com/microprofile/microprofile-tutorial-ui repository +2. Make your customizations following the project's README +3. Build the UI bundle using `gulp bundle` +4. Host the resulting ZIP file (e.g., on GitHub Releases) +5. Update the `url` in `antora-assembler.yml` to point to your custom bundle + +This approach provides the most flexibility but requires more maintenance. + +## Advanced UI Bundle Configuration + +The UI bundle configuration in Antora offers several advanced options that can enhance the documentation site's functionality and performance. + +### Bundle Cache Control + +You can control how Antora handles UI bundle caching: + +[source,yaml] +---- +ui: + bundle: + url: https://github.com/microprofile/microprofile-tutorial-ui/releases/download/latest/ui-bundle.zip + snapshot: true # Always fetch the latest version + # snapshot: false # Use cached version when available +---- + +Setting `snapshot: false` can improve build performance by using a cached version of the bundle. + +### Custom UI Bundle Features + +Modern UI bundles for Antora can include advanced features: + +1. **Search Integration**: Many UI bundles include built-in search functionality: ++ +[source,yaml] +---- +ui: + bundle: + url: https://github.com/microprofile/microprofile-tutorial-ui/releases/download/latest/ui-bundle.zip + supplemental_files: ./supplemental-ui +search: + engine: lunr # Or another search engine + index_latest_only: true +---- + +2. **Multiple Output Formats**: Some UI bundles support different output formats: ++ +[source,yaml] +---- +ui: + bundle: + url: https://github.com/microprofile/microprofile-tutorial-ui/releases/download/latest/ui-bundle.zip +output: + dir: ./build/site + formats: + - html + - pdf +---- + +3. **SEO Optimizations**: Enhanced metadata for search engines: ++ +[source,yaml] +---- +site: + title: MicroProfile Tutorial + url: https://microprofile.io + keys: + seo_description: Comprehensive tutorial for learning MicroProfile + seo_keywords: microprofile, java, cloud-native, microservices +---- + +### Using a Local UI Bundle + +For development or customization, you can use a local UI bundle: + +[source,yaml] +---- +ui: + bundle: + url: ./path/to/local/ui-bundle.zip + snapshot: true +---- + +Replace _./path/to/local/ui-bundle.zip_ with actual path to your local UI bundle under development. + +This approach is useful when developing your own UI bundle or testing modifications. + +### UI Bundle Development + +If you decide to develop your own UI bundle: + +1. **Prerequisites**: Node.js and Gulp +2. **Project Structure**: + - `src/`: Source files (CSS, JavaScript, Handlebars templates) + - `gulp.d/`: Gulp tasks for building the bundle + - `preview-src/`: Sample content for testing +3. **Build Process**: + - Run `gulp bundle` to create the UI bundle + - Use `gulp preview` to test with sample content + +### Performance Optimization Tips + +To optimize the performance of your documentation site: + +1. **Minification**: Ensure CSS and JavaScript are minified +2. **Image Optimization**: Use optimized images and consider lazy loading +3. **Font Subsetting**: Only include the character sets you need +4. **Resource Caching**: Configure proper caching headers +5. **CDN Integration**: Consider hosting assets on a CDN + +### Debugging UI Issues + +When troubleshooting UI problems: + +1. Use browser developer tools to inspect elements and styles +2. Check the browser console for JavaScript errors +3. Verify that all required resources are loading correctly +4. Test with different browsers to identify browser-specific issues