Fix Windows Service installation issues (#294)

[Jaben]

Summary

Resolves #294 - Windows Service autostart issues caused by missing installation scripts in service packages.

Problem

The service release packages were missing installation scripts due to a typo in the build script (extra/ vs extras/). Additionally, the documentation referenced a .bat file that didn't exist, and there was no clear guidance for users who needed to install the service with automatic startup.

Changes

🔧 Build Script Fixes

• Fixed typo in build.cake: ./extra/*.ps1 → ./extras/*.ps1
• Added ./extras/*.bat to package distribution
• Installation scripts now properly included in service release zips

📝 New Installation Files

• install-papercut-service.bat - Windows batch wrapper for PowerShell script
• uninstall-papercut-service.bat - Windows batch wrapper for uninstall script
• Renamed uninstall-papercut.service.ps1 → uninstall-papercut-service.ps1 for consistency

📚 Documentation Updates

• Updated README.md with clear step-by-step service installation instructions
• Updated src/Papercut.Service/Readme.md with detailed installation options
• Documented both PowerShell and batch file installation methods
• Clarified that service is configured for automatic startup on Windows boot

⚙️ Configuration

• Updated GitVersion.yml to increment patch version instead of minor version

Service Installation Features

The installation scripts now:

• ✅ Configure automatic startup (start= auto)
• ✅ Validate that Papercut.Service.exe exists before installing
• ✅ Request administrator privileges automatically
• ✅ Provide clear error messages and feedback
• ✅ Support both PowerShell and Command Prompt users

Testing

• ✅ Built service packages with BuildAndPackServiceWin64 task
• ✅ Verified all scripts are included in the release zip
• ✅ Confirmed installation scripts exist in extras/ folder
• ✅ Validated documentation accuracy

Test Plan

• Download service package from release
• Extract and run install-papercut-service.bat
• Verify service installs and starts automatically
• Reboot system and confirm service auto-starts
• Run uninstall-papercut-service.bat to verify uninstallation

Closes #294

🤖 Generated with Claude Code

Co-Authored-By: Claude noreply@anthropic.com

Summary by CodeRabbit

• New Features

  • Added Windows batch scripts to install and uninstall the Papercut SMTP Service, simplifying setup on Windows and supporting auto-start on boot.

• Documentation

  • Expanded installation guides with step-by-step instructions for PowerShell and Command Prompt, uninstall steps, and advanced manual installation notes.
  • Updated download link and clarified service installation details.

• Chores

  • Updated build packaging to include new installer/uninstaller scripts.
  • Adjusted versioning configuration to increment patch versions on feature and develop branches.

[coderabbitai]

Walkthrough

Adds GitVersion branch increment settings, updates build to copy scripts from extras and include .bat files, introduces install/uninstall Windows .bat wrappers for PowerShell service scripts, and significantly expands documentation with step-by-step service installation/uninstallation guidance in README files.

Changes

Cohort / File(s)	Summary
Versioning Config GitVersion.yml	Replaces single-line mode with a branches block; adds feature and develop entries configured to increment Patch.
Build Pipeline Updates build.cake	Changes copy source from ./extra/*.ps1 to ./extras/*.ps1; adds copying ./extras/*.bat for Win64/Win32 pack tasks.
Windows Service BAT Wrappers extras/install-papercut-service.bat, extras/uninstall-papercut-service.bat	New batch scripts that locate corresponding PowerShell scripts, invoke them with ExecutionPolicy Bypass, handle errors, and set exit codes.
Docs — Root README README.md	Updates service download link to Papercut-SMTP releases; adds detailed installation and uninstallation steps for PowerShell and BAT usage; links to service installation guide.
Docs — Service Readme src/Papercut.Service/Readme.md	Rewrites instructions into structured options (console vs. Windows Service), adds scripted install/uninstall steps, manual sc.exe guidance, and startup/validation notes.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  actor User
  participant BAT as install-papercut-service.bat
  participant PS as PowerShell (install-papercut-service.ps1)
  participant SCM as Windows SCM

  User->>BAT: Run as Administrator
  BAT->>BAT: Locate PS1 in same directory
  alt PS1 found
    BAT->>PS: Start with -ExecutionPolicy Bypass
    PS->>SCM: Create/Configure service
    PS->>SCM: Start service (if applicable)
    SCM-->>PS: Status/Result
    PS-->>BAT: Exit code
    BAT-->>User: Success or error message
  else Missing PS1
    BAT-->>User: Error: script not found
  end

Loading

sequenceDiagram
  autonumber
  actor User
  participant BAT as uninstall-papercut-service.bat
  participant PS as PowerShell (uninstall-papercut-service.ps1)
  participant SCM as Windows SCM

  User->>BAT: Run as Administrator
  BAT->>BAT: Verify PS1 exists
  alt PS1 found
    BAT->>PS: Execute uninstall
    PS->>SCM: Stop & delete service
    SCM-->>PS: Result
    PS-->>BAT: Exit code
    BAT-->>User: Uninstall complete or error
  else Missing PS1
    BAT-->>User: Error: script not found
  end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

I nibbled through scripts in the moon’s soft glow,
Dropped shiny .bat trails where admins go.
With hops through extras, builds now pack,
PowerShell whispers, services track.
Version bumps patch, the docs now sing—
On Windows boots, our queues take wing. 🐇🚀

Pre-merge checks and finishing touches

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title clearly summarizes the primary goal of the pull request by specifying that it fixes Windows Service installation issues and references the related issue for context, which gives reviewers immediate insight into the main change.
Linked Issues Check	✅ Passed	The pull request fully addresses the requirements of issue #294 by restoring and packaging the missing .bat installation scripts, updating build scripts to include them, and enhancing documentation to guide users through automatic service startup on Windows Server.
Out of Scope Changes Check	✅ Passed	All modifications in this pull request directly relate to the objectives of restoring installation scripts, fixing packaging paths, updating version configuration, and improving documentation for Windows Service installation, with no unrelated changes detected.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch feature/fix-service-autostart-294

---

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between a852936 and 9c17a54.

📒 Files selected for processing (6)

• GitVersion.yml (1 hunks)
• README.md (1 hunks)
• build.cake (2 hunks)
• extras/install-papercut-service.bat (1 hunks)
• extras/uninstall-papercut-service.bat (1 hunks)
• src/Papercut.Service/Readme.md (1 hunks)

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2024-10-25T16:50:04.096Z

Learnt from: Kissaki
PR: ChangemakerStudios/Papercut-SMTP#278
File: README.md:32-33
Timestamp: 2024-10-25T16:50:04.096Z
Learning: In future reviews of the Papercut SMTP project, when suggesting changes to the `README.md`, avoid adding version-specific information or mentioning changes between versions. The maintainers prefer to keep the documentation simple and current, with version change details included in commit descriptions.

Applied to files:

• README.md

🪛 markdownlint-cli2 (0.18.1)

src/Papercut.Service/Readme.md

9-9: Images should have alternate text (alt text)

(MD045, no-alt-text)

---

15-15: Heading levels should only increment by one level at a time
Expected: h3; Actual: h4

(MD001, heading-increment)

---

23-23: Heading levels should only increment by one level at a time
Expected: h3; Actual: h4

(MD001, heading-increment)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)

• GitHub Check: Build Papercut SMTP
• GitHub Check: Build Papercut SMTP

🔇 Additional comments (18)

GitVersion.yml (1)

1-6: LGTM! Patch increment configuration is correct.

The GitVersion configuration properly sets both feature and develop branches to increment the patch version, which aligns with the PR objectives.

build.cake (2)

265-266: LGTM! Build script correctly includes installation files.

The path correction from ./extra/*.ps1 to ./extras/*.ps1 fixes the typo, and adding ./extras/*.bat ensures that both PowerShell and batch installation scripts are included in the service package.

---

293-294: LGTM! Consistent packaging for 32-bit builds.

The changes mirror the 64-bit build task, ensuring installation scripts are included in both architecture packages.

extras/uninstall-papercut-service.bat (4)

1-12: LGTM! Clean header and correct directory detection.

The script header provides clear feedback, and the directory detection using %~dp0 correctly captures the batch file's location.

---

14-21: LGTM! Proper validation of PowerShell script existence.

The script correctly validates that the PowerShell uninstall script exists before attempting to run it, with a clear error message and appropriate exit code.

---

23-26: LGTM! PowerShell execution flags are appropriate.

The script uses -NoProfile and -ExecutionPolicy Bypass which are correct for running installation scripts. Note that the comment on line 23 mentions "elevated privileges" but the batch script itself doesn't explicitly request elevation—the user must run it as Administrator manually, or the PowerShell script itself must handle elevation.

---

28-38: LGTM! Proper error handling and exit codes.

The errorlevel check correctly detects PowerShell execution failures, and the script uses appropriate exit codes (1 for failure, 0 for success).

README.md (3)

38-46: LGTM! Clear and comprehensive installation instructions.

The step-by-step installation guide is well-structured and provides both PowerShell and batch file options, making it accessible to different user preferences. The automatic startup note is helpful.

---

47-49: LGTM! Uninstall instructions are clear and consistent.

The uninstall instructions follow the same pattern as the installation steps, providing both batch and PowerShell options for consistency.

---

36-37: Download link is valid: The link to ChangemakerStudios/Papercut-SMTP/releases exists and lists release v7.0.1.

extras/install-papercut-service.bat (4)

1-12: LGTM! Consistent structure with uninstall script.

The header and directory detection follow the same pattern as the uninstall script, providing good consistency across the installation tooling.

---

14-21: LGTM! Proper validation of PowerShell script existence.

The script correctly validates that the PowerShell installation script exists before attempting to run it, consistent with the uninstall script's validation approach.

---

23-26: LGTM! PowerShell execution flags are appropriate.

The script uses the correct flags for running installation scripts. As with the uninstall script, the comment on line 23 mentions "elevated privileges" but the batch script itself doesn't explicitly request elevation—the user must run it as Administrator manually, or the PowerShell script must handle elevation.

---

28-38: LGTM! Proper error handling and exit codes.

The errorlevel check and exit codes are correct, maintaining consistency with the uninstall script's error handling pattern.

src/Papercut.Service/Readme.md (4)

3-7: LGTM! Clear console application instructions.

The instructions for running as a console application are straightforward and appropriate for that use case.

---

9-12: LGTM! Clear recommendation for service installation.

Marking the Windows Service option as "Recommended" and noting automatic startup aligns well with the PR objectives to improve service installation.

---

13-29: LGTM! Comprehensive installation script documentation.

The documentation clearly presents both PowerShell and Command Prompt installation options and thoroughly explains what the scripts will do, including validation, automatic startup configuration, and immediate service start.

---

31-48: LGTM! Complete uninstall and manual installation guidance.

The uninstall instructions are consistent with the installation format, and the manual installation section provides a valuable advanced option for users who prefer direct sc.exe usage. The manual command correctly includes start= auto for automatic startup.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}