Skip to content

Browser-based PR preview capability #1

New issue
New issue
Open
Open
Browser-based PR preview capability#1
@IanMayo

Description

@IanMayo
IanMayo
opened on Oct 24, 2025

Product Requirements Document: JavaFX PR Preview System

Version: 2.1
Date: October 24, 2025
Author: Doc Boeuf

1. Overview

1.1 Purpose

Enable automated preview of JavaFX desktop application changes in pull requests through ephemeral, containerized web applications accessible via standard web browser.

1.2 Problem Statement

  • JavaFX is a desktop GUI framework requiring a display environment
  • Reviewing UI changes in PRs currently requires local checkout and build
  • Working from Chromebook makes local JavaFX testing impractical
  • Need remote, on-demand preview capability for PR review workflow

1.3 Solution Summary

Deploy ephemeral Fly.io Apps for each PR, using JPro to render the JavaFX application as a browser-based web application. Apps are created on PR open/update and destroyed on PR close. This approach eliminates the need for VNC, remote desktop, or complex display server configuration.

JPro Licensing: This project qualifies for JPro's free tier as it is for development and trial purposes only, not commercial production use.

2. Goals and Non-Goals

2.1 Goals

  • Automate preview environment creation for every PR
  • Provide native browser-based access to running JavaFX application (no plugins)
  • Minimize manual GitHub Actions workflow logic
  • Keep preview environments isolated per PR
  • Automatic cleanup when PRs close
  • Cost-effective (only run when needed)
  • Simple, direct HTTPS access without VNC complexity

2.2 Non-Goals

  • Multi-user concurrent access to same preview
  • Production deployment pipeline
  • Persistent state between PR updates
  • Native desktop application deployment
  • Automated UI testing or screenshot comparison
  • Support for JavaFX features incompatible with JPro

3. Architecture

3.1 Components

3.1.1 Docker Container

Base Image: Ubuntu or Debian (or JPro-provided base image)
Included Software:

  • Java Development Kit (version matching project requirements)
  • JavaFX runtime
  • JPro server (web rendering engine for JavaFX)
  • Build tools (Maven or Gradle, as per project)
  • Git client

Entrypoint Script Responsibilities:

  1. Clone GitHub repository from environment variable
  2. Checkout PR branch from environment variable
  3. Execute build command (Maven/Gradle with JPro plugin)
  4. Start JPro server
  5. JPro server renders JavaFX app as web application
  6. Keep container running and serving web traffic

3.1.2 Fly.io App

Type: Fly App (standard web application deployment)
Lifecycle: Created per PR, destroyed on PR close
Configuration:

  • Smallest viable app instance size
  • Single instance (no scaling needed)
  • Ephemeral storage acceptable
  • Public HTTPS endpoint (Fly.io provides SSL certificate)
  • Health check endpoint for JPro server

3.1.3 GitHub Actions Workflow

Triggers:

  • pull_request events: opened, synchronize
  • pull_request events: closed

PR Open/Update Jobs:

  1. Build Docker image with JPro configuration
  2. Deploy to Fly.io Apps via flyctl deploy
  3. Pass environment variables:
    • GITHUB_REPO: Repository URL
    • PR_BRANCH: Branch name
    • GITHUB_TOKEN: For private repo access (if needed)
  4. Wait for health check endpoint
  5. Post PR comment with application URL
  6. Store app name in workflow artifacts or GitHub environment

PR Close Jobs:

  1. Retrieve app name
  2. Destroy Fly.io App via flyctl apps destroy

3.2 Data Flow

PR Opened/Updated
    ↓
GitHub Actions triggered
    ↓
Build Docker image with JPro + JavaFX app
    ↓
Deploy to Fly.io Apps
    ↓
Container starts, runs entrypoint script
    ↓
Script: Clone repo → Checkout branch → Build → Start JPro server
    ↓
JPro renders JavaFX app in browser (HTML5/WebGL)
    ↓
Application accessible via HTTPS URL
    ↓
GitHub Actions posts URL as PR comment
    ↓
Developer accesses via Chrome browser on Chromebook
    ↓
PR Closed → GitHub Actions destroys app

4. Technical Requirements

4.1 Dockerfile Requirements

  • Multi-stage build to minimize image size
  • JPro server configuration and dependencies
  • Health check endpoint (HTTP 200 on JPro server port, typically 8080)
  • Configurable via environment variables:
    • Repository URL
    • Branch name
    • Build command override (optional)
    • GitHub token (for private repos)
  • Logging to stdout for Fly.io log aggregation
  • Graceful shutdown handling

4.2 GitHub Actions Requirements

  • Secrets management:
    • FLY_API_TOKEN: Fly.io API authentication
    • GITHUB_TOKEN: Already provided by GitHub Actions
  • Conditional execution (only for repository with JavaFX code)
  • Error handling and retry logic
  • App name persistence between workflow jobs
  • PR comment formatting with clear instructions
  • Timeout limits (suggest 30 minutes max for build and deploy)

4.3 Security Requirements

  • HTTPS for all application access (Fly.io provides this automatically)
  • Optional HTTP basic authentication for additional access control
  • No sensitive data in Dockerfile or logs
  • GitHub token scoped to minimum required permissions
  • App access limited to PR duration
  • Rate limiting consideration for PR creation

4.4 Performance Requirements

  • Docker image build: < 3 minutes
  • Application build and JPro startup: < 4 minutes (project dependent)
  • Total time from PR open to accessible preview: < 7 minutes
  • Browser rendering: Native web performance (no VNC latency)
  • First paint: < 2 seconds after URL access

4.5 JPro Integration Requirements

  • JPro Maven or Gradle plugin configured in project
  • JavaFX application compatible with JPro's rendering engine
  • Testing of JPro compatibility during Phase 1 (MVP)
  • Documentation of any JavaFX features with JPro limitations

5. User Experience

5.1 Developer Workflow

  1. Create Pull Request

    • Developer pushes changes and opens PR
    • GitHub Actions automatically triggered (no manual intervention)

  2. Wait for Preview

    • Bot comments on PR: "🚀 Building preview environment..."
    • After ~5-7 minutes: "✅ Preview ready: [URL]"

  3. Access Preview

    • Click URL in PR comment
    • Opens JavaFX application directly in browser tab
    • No plugins, passwords, or VNC client needed
    • Native web application experience

  4. Review and Iterate

    • Push additional commits to PR
    • Preview environment automatically recreated
    • Old app destroyed, new app deployed

  5. Close PR

    • Merge or close PR
    • App automatically destroyed
    • Resources cleaned up

5.2 PR Comment Format

## 🚀 JavaFX Preview Environment

**Status:** ✅ Ready  
**Access:** [Launch Preview](https://javafx-preview-pr-123.fly.dev)

**Instructions:**
1. Click the preview link above
2. Application will load directly in your browser
3. Interact with your JavaFX application to review changes

**Build Log:** [View on Fly.io](https://fly.io/apps/javafx-preview-pr-123/logs)

**Note:** This is a web-rendered version of your JavaFX app using JPro. Some advanced JavaFX features may have limitations.

---
_Preview environment will be automatically destroyed when this PR is closed._
_App: `javafx-preview-pr-123` | Built from: `<commit-sha>`_

6. Cost Estimation

6.1 Project Context

This is a development and trial project, which qualifies for JPro's free tier. Therefore, JPro licensing costs are $0.

6.2 Fly.io Pricing (as of Oct 2024)

  • Apps pricing: ~$0.0000008/second for compute
  • Smallest app suitable for JavaFX with JPro: ~$0.0029/hour
  • Storage: First 3GB free per org
  • Bandwidth: First 100GB outbound free per month

6.3 Total Cost Scenarios

Light Usage (5 PRs/week, 30min each):

  • 2.5 hours/week × 4 weeks = 10 hours/month
  • Total Cost: ~$0.03/month

Medium Usage (20 PRs/week, 45min each):

  • 15 hours/week × 4 weeks = 60 hours/month
  • Total Cost: ~$0.17/month

Heavy Usage (50 PRs/week, 1hr each):

  • 50 hours/week × 4 weeks = 200 hours/month
  • Total Cost: ~$0.58/month

6.4 Cost Summary

  • JPro: $0 (free tier for development/trial use)
  • Fly.io: $0.03 - $0.58/month (depending on usage)
  • Total: Essentially free for typical development workflow

Note: If this project transitions to commercial/production use in the future, JPro licensing would need to be reevaluated. For the current development/trial scope, all costs are covered by free tiers or minimal Fly.io compute charges.

7. Implementation Phases

Phase 0: Foundation

Goal: Placeholder app, used for testing

Deliverables:

  • Very simple Hello World JavaFx app
  • Properly configured maven files (including pom.xml) that allow the project to be fully built using one build command

Success Criteria:

  • Executing a single command builds and runs the Hello World JavaFx app.

Phase 1: MVP (Proof of Concept)

Goal: Single working preview for one PR

Deliverables:

  • Basic Dockerfile with JPro + JavaFX
  • JPro Maven/Gradle plugin integration in project
  • Manual Fly.io App deployment (no automation)
  • Verify browser access from Chromebook
  • Confirm JavaFX app renders correctly in browser via JPro
  • Test all critical JavaFX features for JPro compatibility

Success Criteria:

  • Can access running JavaFX app via browser (no plugins needed)
  • UI is responsive and performant
  • Core JavaFX features work correctly with JPro
  • Identify any JPro limitations affecting the application

Phase 2: Automation

Goal: GitHub Actions integration

Deliverables:

  • GitHub Actions workflow for PR open/update
  • GitHub Actions workflow for PR close/cleanup
  • Automated PR commenting with preview URL
  • Environment variable passing (repo, branch, token)
  • Error handling and logging

Success Criteria:

  • Preview automatically created on PR open
  • Machine automatically destroyed on PR close
  • Developer receives clear PR comment with access info
  • No manual intervention required

Phase 3: Refinement

Goal: Production-ready reliability

Deliverables:

  • Security hardening (token management, optional basic auth)
  • Performance optimization (Docker layer caching, build time)
  • Better error messages in PR comments
  • Health checks and timeout handling
  • Documentation for team onboarding

Success Criteria:

  • 95% success rate for preview creation
  • Clear error messages when failures occur
  • Team successfully uses system without support
  • Build time < 5 minutes

Phase 4: Enhancements (Optional)

Future improvements:

  • Multiple preview versions (keep previous commits accessible)
  • Screenshot automation on build
  • Integration with PR status checks
  • Custom domains per PR
  • Support for multiple concurrent PRs from same developer

8. Risks and Mitigations

8.1 Technical Risks

Risk Impact Probability Mitigation
Fly.io app deployment timeout High Low Implement retry logic, fallback to error comment
Build failures in container Medium Medium Capture build logs, post in PR comment, fail gracefully
JPro rendering issues or incompatibilities High Medium Test thoroughly in Phase 1, document limitations, maintain fallback plan
GitHub Actions concurrent PR limit Medium Low Queue system or limit concurrent builds
Orphaned apps (cleanup failure) Low Medium Regular audit script, app tagging, TTL limits
JPro performance issues Medium Low Load testing during Phase 1, consider instance sizing

8.2 Cost Risks

Risk Impact Probability Mitigation
Forgotten running apps Medium Medium Aggressive timeouts, billing alerts, regular audits
Large image size → slow builds Low High Multi-stage builds, layer caching, optimize JPro dependencies
Excessive PR churn Low Low Rate limiting, cost monitoring dashboard
Project transitions to commercial use Low Low Monitor usage, reevaluate JPro licensing if needed

8.3 Security Risks

Risk Impact Probability Mitigation
Token leakage in logs High Medium Mask tokens in scripts, audit log output
Public access to preview Low Low Accept as design choice, or add HTTP basic auth if needed
Malicious code in PR High Low Manual approval for external contributors, sandboxed environment

8.4 JPro-Specific Risks

Risk Impact Probability Mitigation
JavaFX features not supported by JPro High Medium Comprehensive testing in Phase 1, maintain feature compatibility matrix
JPro free tier restrictions change Low Low Monitor JPro announcements, project is within free tier scope
JPro server stability issues Medium Low Implement health checks, automatic restarts, fallback error handling
Project grows beyond free tier scope Low Low Document current usage, plan for commercial licensing if needed

9. Success Metrics

9.1 Quantitative Metrics

  • Preview creation success rate: > 95%
  • Time to preview availability: < 7 minutes (P95)
  • Cost per PR preview: < $0.01
  • Machine cleanup rate: 100% (no orphans)

9.2 Qualitative Metrics

  • Developer satisfaction: Positive feedback on ease of use
  • Adoption rate: % of PRs using preview feature
  • Support requests: < 1 per week after Phase 3

10. Dependencies

10.1 External Services

  • Fly.io: App hosting, networking, billing
  • GitHub: Actions runtime, API, secrets management
  • JPro: JavaFX to web rendering engine and licensing

10.2 Technical Dependencies

  • Docker (for image building)
  • flyctl CLI (Fly.io control)
  • Project build system (Maven/Gradle)
  • JPro Maven or Gradle plugin
  • JavaFX version compatibility with JPro
  • Java version compatible with JPro

10.3 Account Requirements

  • Fly.io account with payment method
  • GitHub repository with Actions enabled
  • Access to repository secrets configuration
  • JPro account (free tier for evaluation, paid for production use)

10.4 JPro Requirements

  • JPro plugin added to Maven/Gradle build file
  • JavaFX application structure compatible with JPro
  • Testing of application features against JPro compatibility matrix
  • Project qualifies for JPro free tier (development/trial use)

11. Open Questions

  1. Build tool: Maven or Gradle? (Document in PRD or make configurable)
  2. Java version: Which JDK version does the project require?
  3. JavaFX version: Which version, and is it compatible with JPro?
  4. App instance size: What's minimum viable for acceptable JPro performance?
  5. Timeout policy: How long should apps stay alive? (Suggest 1-2 hours)
  6. Concurrent PR limit: Should we limit number of active previews?
  7. Access control: Public access acceptable or need HTTP basic auth?
  8. Build caching: Should we cache dependencies between builds?
  9. JPro compatibility: Are there specific JavaFX features in the app that need testing with JPro?
  10. Fallback plan: If JPro doesn't work, do we revert to VNC approach?

12. Documentation Requirements

12.1 Developer Documentation

  • README section explaining preview feature
  • How to access preview from PR
  • Troubleshooting common issues
  • How to opt-out of preview (if needed)

12.2 Operational Documentation

  • Fly.io setup instructions
  • GitHub secrets configuration
  • Manual machine cleanup procedure
  • Cost monitoring and budgeting
  • Dockerfile maintenance guide

12.3 Architecture Documentation

  • System diagram
  • Data flow diagrams
  • Sequence diagrams for key workflows
  • Security model documentation

13. Acceptance Criteria

The feature is complete when:

  • Developer opens PR, preview is automatically created
  • PR comment contains working application URL
  • Browser access from Chromebook successfully shows running JavaFX app (no plugins)
  • UI is interactive and responsive for review purposes
  • All critical JavaFX features work correctly via JPro
  • PR updates trigger new preview (old app destroyed)
  • PR close triggers app cleanup
  • No manual intervention required for happy path
  • Error states result in clear PR comments
  • Documentation is complete and accurate
  • Cost per preview is < $0.01 (Fly.io compute only)
  • Preview available within 7 minutes of PR open
  • Team successfully uses system without support requests

14. Future Considerations

14.1 Potential Enhancements

  • Automated screenshot capture for visual regression
  • Integration with design tools for UI spec comparison
  • Recording of interaction sessions for asynchronous review
  • Parallel testing with different Java/JavaFX versions
  • Performance monitoring and metrics for JPro rendering
  • A/B testing between JPro and native desktop versions

14.2 Scalability

  • Current design suitable for small-medium teams (< 50 developers)
  • For larger scale, consider:
    • Shared base images with PR-specific builds
    • Pre-warmed app instances
    • Dedicated Fly.io organization for cost tracking
    • App instance size auto-scaling based on load
    • CDN for JPro static assets

14.3 Alternative/Fallback Approaches

  • VNC approach: If JPro proves incompatible, fall back to VNC-based preview (see Appendix A.5)
  • Hybrid approach: Use JPro for most previews, VNC for specific feature testing
  • Native builds: Explore GitHub-hosted runners with native display for Windows/macOS testing

Appendix A: Technology Alternatives Considered

A.1 JPro Web Rendering (CHOSEN APPROACH)

Pros:

  • Native browser experience (no VNC lag)
  • Simple deployment model (standard Fly.io Apps)
  • No VNC/remote desktop complexity
  • Better performance and user experience
  • Direct HTTPS access
  • Simpler security model

Cons:

  • JPro licensing costs (free tier may suffice for small projects)
  • Potential JavaFX feature limitations
  • Dependency on third-party service (JPro)
  • Requires JPro compatibility testing

Decision: Selected as primary approach for superior UX and simplicity

A.2 VNC + noVNC Approach (FALLBACK)

Pros:

  • Works with any JavaFX application
  • No JavaFX feature limitations
  • No third-party dependencies beyond infrastructure

Cons:

  • Complex setup (VNC server, display management, window manager)
  • VNC password management required
  • Potential performance/latency issues
  • More complex security requirements
  • Requires Fly.io Machines instead of Apps

Decision: Retained as fallback if JPro proves incompatible

A.3 GitHub Actions + Tunneling (ngrok/cloudflared)

Pros: No external VM service needed
Cons: 6-hour GitHub Actions limit, complex tunnel setup, less reliable
Decision: Rejected in favor of dedicated hosting

A.4 Always-Running Fly Machine

Pros: Faster preview startup, persistent environment
Cons: Higher cost, manual lifecycle management, state management complexity
Decision: Rejected in favor of ephemeral per-PR instances

A.5 Alternative Platforms (DigitalOcean, AWS EC2, Hetzner)

Pros: More VM-like behavior, potentially cheaper
Cons: More setup complexity, less integrated with existing workflow (code-server on Fly.io)
Decision: Fly.io chosen for consistency with existing infrastructure

A.6 Screenshot/Recording Only (No Interactive Preview)

Pros: Simpler, cheaper, no runtime environment needed
Cons: Cannot interact with UI, limited review capability
Decision: Rejected as insufficient for meaningful UI review

Appendix B: Example Commands

B.1 Manual App Deployment (Testing)

# Deploy app from Dockerfile
fly deploy \
  --app javafx-preview-pr-123 \
  --region lhr \
  --env GITHUB_REPO=https://github.com/user/repo \
  --env PR_BRANCH=feature-branch \
  --env GITHUB_TOKEN=$GITHUB_TOKEN

# Or using fly.toml configuration
fly deploy --config fly.toml

B.2 App Cleanup

# Destroy the app and all resources
fly apps destroy javafx-preview-pr-123 --yes

B.3 View Logs

# View real-time logs
fly logs --app javafx-preview-pr-123

# View historical logs
fly logs --app javafx-preview-pr-123 --timestamp

B.4 Check App Status

# Get app information
fly status --app javafx-preview-pr-123

# Check app health
fly checks list --app javafx-preview-pr-123

B.5 JPro Maven Plugin Example

<plugin>
    <groupId>com.sandec.jpro</groupId>
    <artifactId>jpro-maven-plugin</artifactId>
    <version>2024.1.0</version>
    <configuration>
        <mainClassName>com.example.MainApp</mainClassName>
        <jpro>
            <port>8080</port>
        </jpro>
    </configuration>
</plugin>

B.6 JPro Gradle Plugin Example

plugins {
    id 'com.sandec.jpro' version '2024.1.0'
}

jpro {
    mainClassName = 'com.example.MainApp'
    port = 8080
}

Appendix C: JPro Overview

C.1 What is JPro?

JPro is a technology that allows JavaFX applications to run in a web browser without plugins. It works by:

  • Running the JavaFX application on the server
  • Rendering the UI as HTML5/WebGL in the browser
  • Handling user interactions and synchronizing state between server and client

C.2 JPro Architecture

Browser (Client)                    Server
    ↓                                  ↓
HTML5/WebGL UI           ←→      JavaFX Application
    ↓                                  ↓
User interactions        →       JPro Server
    ↓                                  ↓
Visual updates           ←       Application logic

C.3 JPro Compatibility

Well-Supported JavaFX Features:

  • Standard controls (Button, TextField, Label, etc.)
  • Layouts (VBox, HBox, BorderPane, GridPane, etc.)
  • CSS styling
  • FXML
  • Charts
  • WebView (with limitations)
  • Media playback (with limitations)

Potential Limitations:

  • Native file system access (use JPro's file chooser API)
  • Some 3D rendering features
  • Hardware acceleration dependencies
  • Very complex custom controls may need testing
  • Performance may differ from native JavaFX

C.4 JPro Licensing Options

For This Project:
This project qualifies for JPro's free tier as it is for development and trial purposes only, not commercial production use. No license key or payment required.

General JPro Licensing:

  • Free Tier: Open-source projects, evaluation, development, and personal projects
  • Commercial License: Private/commercial projects in production, enterprise support, custom terms available

Future Considerations:
If this project transitions to commercial/production use, JPro licensing would need to be reevaluated. For the current scope, the free tier covers all needs.

C.5 JPro Resources

C.6 Integration Checklist

  • Add JPro plugin to build file (Maven or Gradle)
  • Configure main class name
  • Test application locally with JPro
  • Verify all critical features work
  • Document any feature limitations
  • Confirm project qualifies for free tier (development/trial use)

Revision History

Version Date Author Changes
1.0 2025-10-24 Doc Boeuf Initial PRD creation (VNC approach)
2.0 2025-10-24 Doc Boeuf Major revision: Changed from VNC/noVNC approach to JPro web rendering for simpler deployment and better UX
2.1 2025-10-24 Doc Boeuf Clarified JPro free tier usage: Project qualifies as development/trial, removed all license key management requirements
2.2 2025-10-24 Doc Boeuf Introduce task to create Hello World placeholder project

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions