[PBI] Local Jenkins Installation & Smoke Test Guide

[cjlapao]

Description

Produce a step-by-step guide for installing the compiled .hpi on a local Jenkins instance (for testing or evaluation), configuring the Cloud provider from scratch, and running a smoke test build. This bridges the gap between "I have the .hpi file" and "my first dynamic VM agent is running a build".

User Story

As a developer or QA engineer evaluating the plugin, I want a clear step-by-step guide to install and smoke test the plugin on a local Jenkins so that I can verify the plugin works in a real environment without guessing the setup steps.

Acceptance Criteria

• Document covers prerequisites: Lists required software (Jenkins LTS, JDK 17, prl-devops-service running and reachable) and their minimum versions.
• HPI installation steps: Documents both routes:
  1. Via Plugin Manager UI: Manage Jenkins → Plugins → Advanced → Upload Plugin.
  2. Via CLI: java -jar jenkins-cli.jar -s http://localhost:8080 install-plugin parallels-cloud.hpi -restart.
• Cloud configuration walkthrough: Step-by-step screenshots or CLI commands covering:
  • Adding the Cloud (Manage Jenkins → Clouds).
  • Entering service URL, credentials, connection mode.
  • Clicking Test Connection.
  • Adding an Agent Template (label, base VM name, SSH credentials, retention policy).
  • Saving configuration.
• Smoke test job: Instructions to create a freestyle job with the agent label, run it, observe the dynamic VM appearing in Nodes, the build running, and the VM being cleaned up.
• Troubleshooting section: At least 5 common issues documented with diagnosis and resolution (e.g., "Test Connection fails", "VM stuck in PENDING", "SSH connection refused", "Agent goes offline immediately", "VM not deleted after build").
• Document format: Written in Markdown; stored at docs/local-install.md in the plugin repository.

Definition of Done

• Code implemented following best practices.
• Unit tests written and passing.
• Code reviewed and approved.
• Merged into the main branch.
• Documentation updated (if applicable).
• Deployed to staging/production environment.

Assumptions and Constraints

• Assumption 1: Screenshots are optional; CLI commands and descriptive text are sufficient for the guide.
• Assumption 2: The guide targets Jenkins LTS on macOS and Linux; Windows is covered as a secondary note.
• Constraint 1: This is documentation only — no code changes are included in this PBI.

Dependencies

No response

Additional Notes

Document outline

# Installing the Parallels DevOps Jenkins Plugin

## Prerequisites
## Installing the .hpi
  ### Via Plugin Manager UI
  ### Via Jenkins CLI
## Configuring the Cloud Provider
  ### Step 1: Add the Cloud
  ### Step 2: Configure Service Connection
  ### Step 3: Add an Agent Template
  ### Step 4: Test the Configuration
## Running Your First Dynamic Build
## Troubleshooting
  ### Test Connection fails with 401
  ### VM stuck in PENDING state
  ### SSH: Connection refused
  ### Agent goes offline immediately after coming online
  ### VM not deleted after build (ONE_SHOT)
  ### Idle timeout not triggering cleanup