doc updated

2025-12-14 12:15:26 +01:00
parent bcae8557a8
commit e361f26cdf
1 changed files with 301 additions and 31 deletions
@@ -31,30 +31,116 @@ Build and deploy applications on the same machine.

 ---

+## Step 0: Install Chocolatey Package Manager (Recommended)
+
+> **?? Chocolatey Alternative**: Use Chocolatey to automate the installation of prerequisites instead of manual downloads and installations.
+
+### 0.1 Install Chocolatey
+Chocolatey is a powerful package manager for Windows that simplifies software installation and management.
+
+1. **Open PowerShell as Administrator**:
+   - Press `Win + X` and select **"Windows PowerShell (Admin)"** or **"Terminal (Admin)"**
+
+2. **Check Execution Policy** (run this first):
+   ```powershell
+   Get-ExecutionPolicy
+   ```
+   - If it shows `Restricted`, temporarily change it:
+   ```powershell
+   Set-ExecutionPolicy AllSigned
+   ```
+
+3. **Install Chocolatey**:
+   ```powershell
+   Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))
+   ```
+
+4. **Verify Installation**:
+   ```powershell
+   choco --version
+   ```
+
+5. **Restart PowerShell** or run:
+   ```powershell
+   refreshenv
+   ```
+
+### 0.2 Install Prerequisites with Chocolatey
+Once Chocolatey is installed, you can use it to install most prerequisites automatically:
+
+```powershell
+# Install FFmpeg
+choco install ffmpeg -y
+
+# Install yt-dlp
+choco install yt-dlp -y
+
+# Install curl (for testing)
+choco install curl -y
+
+# Optional: Install Git (if not already installed)
+choco install git -y
+
+# Optional: Install 7-Zip (for handling archives)
+choco install 7zip -y
+
+# Optional: Install Notepad++ (for editing config files)
+choco install notepadplusplus -y
+```
+
+**Advantages of using Chocolatey:**
+- ? **Automatic PATH configuration** - No manual PATH editing needed
+- ? **Automatic updates** available via `choco upgrade`
+- ? **Consistent installation** across different machines
+- ? **Easy uninstallation** if needed
+- ? **No manual extraction** or file placement required
+
+### 0.3 Verify Chocolatey Installations
+After installing with Chocolatey, verify the tools are available:
+
+```powershell
+# Verify FFmpeg
+ffmpeg -version
+
+# Verify yt-dlp
+yt-dlp --version
+
+# Verify curl
+curl --version
+```
+
+---
+
 ## Step 1: Install .NET 10 Hosting Bundle for IIS

 > **Critical**: This step is required for ALL deployment scenarios

-### 1.1 Download .NET 10 Hosting Bundle
-The Hosting Bundle contains the ASP.NET Core runtime and IIS integration components needed to run .NET 10 applications on IIS.
+### 1.1 Install .NET 10 Hosting Bundle

+**Option A: Using Chocolatey (Recommended)**
+```powershell
+# Install .NET 10 Hosting Bundle via Chocolatey
+choco install dotnet-hosting -y
+
+# Alternatively, install specific version (replace x.x.x with actual version)
+# choco install dotnet-hosting --version=10.0.x -y
+```
+
+**Option B: Manual Download (Alternative)**
 1. Go to [Microsoft .NET Downloads](https://dotnet.microsoft.com/download/dotnet/10.0)
 2. Scroll to **"ASP.NET Core Runtime"** section
 3. Under **"Run server apps"**, find **"Hosting Bundle"**
 4. Download **"Hosting Bundle"** for Windows (e.g., `dotnet-hosting-10.0.x-win.exe`)
 5. **Important**: This is different from the SDK - it's specifically for IIS hosting

-### 1.2 Install the Hosting Bundle
-1. Close all IIS Manager windows and web browsers
-2. Run the downloaded hosting bundle installer as **Administrator**
-3. Follow the installation wizard:
-   - Accept license terms
-   - Complete the installation
-4. **Critical**: Restart IIS services by running this command in **Command Prompt as Administrator**:
+### 1.2 Complete Hosting Bundle Installation
+1. If installed manually, close all IIS Manager windows and web browsers
+2. If installed manually, run the downloaded hosting bundle installer as **Administrator**
+3. **Critical**: Restart IIS services by running this command in **Command Prompt as Administrator**:
   ```cmd
   iisreset /restart
   ```
-5. Alternatively, restart the entire computer to ensure all services are updated
+4. Alternatively, restart the entire computer to ensure all services are updated

 ### 1.3 Verify Hosting Bundle Installation
 1. Open **Command Prompt as Administrator**
@@ -83,12 +169,23 @@ The Hosting Bundle contains the ASP.NET Core runtime and IIS integration compone

 ## Step 2: Install Required Tools

-### 2.1 Download yt-dlp
+### 2.1 Install Prerequisites with Chocolatey (Recommended)
+
+If you completed **Step 0** above, your prerequisites should already be installed. If not, install them now:
+
+```powershell
+# Open PowerShell as Administrator and run:
+choco install ffmpeg yt-dlp -y
+```
+
+### 2.2 Manual Installation (Alternative to Chocolatey)
+
+#### 2.2.1 Download yt-dlp (Manual)
 1. Go to [yt-dlp releases](https://github.com/yt-dlp/yt-dlp/releases)
 2. Download the latest `yt-dlp.exe` (Windows executable)
 3. **Important**: Keep this file ready for later deployment

-### 2.2 Install FFmpeg
+#### 2.2.2 Install FFmpeg (Manual)
 1. Go to [FFmpeg downloads](https://ffmpeg.org/download.html#build-windows)
 2. Choose **"Windows"** ? **"Windows builds by BtbN"**
 3. Download the latest **"ffmpeg-master-latest-win64-gpl.zip"**
@@ -102,14 +199,43 @@ The Hosting Bundle contains the ASP.NET Core runtime and IIS integration compone
   - Click **OK** to save all dialogs
 6. Restart Command Prompt and verify: `ffmpeg -version`

-### 2.3 Install Let's Encrypt ACME Tool (Production HTTPS)
-For production deployment with custom domains, install an ACME client:
+### 2.3 Install Let's Encrypt ACME Tool
+
+**Option A: Using Chocolatey (Recommended)**
+```powershell
+# Install win-acme for Windows/IIS SSL certificates
+choco install win-acme -y
+```
+
+**Option B: Manual Installation (Alternative)**
+For production deployment with custom domains, install an ACME client manually:

 1. **Install win-acme (Recommended for Windows/IIS)**:
   - Go to [win-acme releases](https://github.com/win-acme/win-acme/releases)
   - Download the latest `win-acme.v2.x.x.x.pluggable.zip`
   - Extract to `C:\win-acme\`

+### 2.4 Verify All Tool Installations
+
+Run these commands to verify all prerequisites are properly installed:
+
+```powershell
+# Check .NET installation
+dotnet --version
+
+# Check FFmpeg
+ffmpeg -version
+
+# Check yt-dlp
+yt-dlp --version
+
+# Check win-acme (if installed via Chocolatey)
+wacs --version
+
+# List all Chocolatey installed packages
+choco list --local-only
+```
+
 ---

 ## Step 3: Get Application Files
@@ -124,6 +250,17 @@ If you have pre-built application files from another machine:
 If you need to build the applications on this machine, continue below:

 #### 3B.1 Install .NET 10 SDK (If Building Locally)
+
+**Option A: Using Chocolatey (Recommended)**
+```powershell
+# Install .NET 10 SDK via Chocolatey
+choco install dotnet-sdk -y
+
+# Or install specific version (replace x.x.x with actual version)
+# choco install dotnet-sdk --version=10.0.x -y
+```
+
+**Option B: Manual Installation (Alternative)**
 1. Go to [Microsoft .NET Downloads](https://dotnet.microsoft.com/download/dotnet/10.0)
 2. Download and install the .NET 10 SDK
 3. Restart your computer after installation
@@ -514,8 +651,11 @@ After deployment, you can verify the files are present:
 1. Check certificate binding in IIS Manager
 2. Verify Let's Encrypt certificate renewal:
   ```cmd
-   # For win-acme
-   wacs.exe --list
+   # For win-acme (Chocolatey installation)
+   wacs --list
+   
+   # For manual win-acme installation
+   C:\win-acme\wacs.exe --list
   
   # For certbot
   certbot certificates
@@ -523,8 +663,11 @@ After deployment, you can verify the files are present:
 3. Check Windows Task Scheduler for renewal tasks
 4. Manually renew if needed:
   ```cmd
-   # For win-acme
-   wacs.exe --renew
+   # For win-acme (Chocolatey installation)
+   wacs --renew
+   
+   # For manual win-acme installation
+   C:\win-acme\wacs.exe --renew
   
   # For certbot
   certbot renew
@@ -564,11 +707,35 @@ After deployment, you can verify the files are present:
 4. Ensure proper MIME types in `web.config`
 5. Verify API base URL is correctly configured in `appsettings.json`

+#### Chocolatey Installation Issues
+**Problem**: Chocolatey packages not installing or commands not found
+**Solutions**:
+1. Verify Chocolatey installation:
+   ```powershell
+   choco --version
+   ```
+2. Refresh environment variables:
+   ```powershell
+   refreshenv
+   ```
+3. Reinstall problematic packages:
+   ```powershell
+   choco uninstall <package-name> -y
+   choco install <package-name> -y
+   ```
+4. Check package installation status:
+   ```powershell
+   choco list --local-only
+   ```
+
 ### 11.2 Verification Commands
 ```cmd
 # Check .NET installation (Hosting Bundle should show runtimes, SDK not required)
 dotnet --list-runtimes

+# Check Chocolatey packages
+choco list --local-only
+
 # Check IIS status
 iisreset /status

@@ -587,6 +754,12 @@ certlm.msc
 # Test HTTPS connectivity
 curl -I https://tuneripper-api.vrba.one/api/health
 curl -I https://tuneripper.vrba.one
+
+# Verify FFmpeg (Chocolatey)
+ffmpeg -version
+
+# Verify yt-dlp (Chocolatey)
+yt-dlp --version
 ```

 ### 11.3 Log Locations
@@ -595,8 +768,10 @@ curl -I https://tuneripper.vrba.one
 - **ASP.NET Core stdout logs**: `C:\inetpub\wwwroot\TuneRipperApi\logs\` (if enabled)
 - **Application-specific logs**: Configure in `appsettings.json`
 - **Let's Encrypt Logs**: 
-  - win-acme: `C:\win-acme\logs\`
+  - win-acme (Chocolatey): Check `choco list win-acme` for installation path
+  - win-acme (Manual): `C:\win-acme\logs\`
  - certbot: `C:\Certbot\log\`
+- **Chocolatey Logs**: `C:\ProgramData\chocolatey\logs\`

 ---

@@ -609,7 +784,8 @@ curl -I https://tuneripper.vrba.one
 4. **Security Headers**: Added to `web.config` (X-Frame-Options, etc.)
 5. **File Upload Limits**: Configure maximum file sizes if needed
 6. **Rate Limiting**: Consider implementing rate limiting for API endpoints
-7. **Update .NET Regularly**: Keep .NET 10 runtime updated via Hosting Bundle
+7. **Update .NET Regularly**: Keep .NET 10 runtime updated via Hosting Bundle or Chocolatey
+8. **Update Chocolatey Packages**: Regularly update packages with `choco upgrade all`

 ### 12.2 Firewall Configuration
 1. Open Windows Defender Firewall
@@ -643,22 +819,64 @@ policy.AllowAnyOrigin()
 - Review and rotate log files
 - Monitor application pool health
 - **Monitor SSL certificate renewals** (should be automatic)
+- **Update Chocolatey packages** regularly

-### 13.2 SSL Certificate Maintenance
- **win-acme**: Automatic renewal via Windows Task Scheduler
+### 13.2 Chocolatey Package Maintenance
+Keep your system updated using Chocolatey's built-in update capabilities:
+
+```powershell
+# Update all installed packages
+choco upgrade all -y
+
+# Update specific packages
+choco upgrade ffmpeg yt-dlp dotnet-hosting -y
+
+# Check for outdated packages
+choco outdated
+
+# Verify installed tools
+ffmpeg -version
+yt-dlp --version
+```
+
+### 13.3 SSL Certificate Maintenance
+- **win-acme (Chocolatey)**: Automatic renewal via Windows Task Scheduler
+- **win-acme (Manual)**: Automatic renewal via Windows Task Scheduler  
 - **certbot**: Set up automatic renewal:
  ```cmd
  # Add to Task Scheduler to run twice daily
  certbot renew --quiet
  ```

-### 13.3 Updating .NET 10
+### 13.4 Updating .NET 10
 When new .NET 10 updates are released:
-1. Download and install **new .NET 10 Hosting Bundle** (SDK not required)
+
+**Option A: Using Chocolatey (Recommended)**
+```powershell
+# Update .NET Hosting Bundle
+choco upgrade dotnet-hosting -y
+
+# If you have SDK installed for development
+choco upgrade dotnet-sdk -y
+```
+
+**Option B: Manual Update (Alternative)**
+1. Download and install **new .NET 10 Hosting Bundle** (SDK not required for production)
 2. Restart IIS: `iisreset`
 3. Test application functionality
 4. Update applications if needed (rebuild only if breaking changes)

+### 13.5 Backup Chocolatey Package List
+Create a backup of your installed packages for easy restoration:
+
+```powershell
+# Export installed packages to a file
+choco export C:\backup\packages.config
+
+# Restore packages from backup (on new machine)
+choco install C:\backup\packages.config
+```
+
 ---

 ## Conclusion
@@ -675,6 +893,7 @@ Your TuneRipper application should now be successfully deployed on IIS with Wind
 - ? **CORS compatibility** with subdomain setup
 - ? **Security headers** configured
 - ? **Automatic certificate renewal** set up
+- ? **Chocolatey package management** for easy updates and maintenance

 ## CORS Compatibility Summary

@@ -689,6 +908,7 @@ For production, you can optionally restrict CORS to specific domains (see Step 7

 ## Quick Reference Commands

+### Basic System Commands
 ```cmd
 # Check .NET 10 runtime installation (production)
 dotnet --list-runtimes
@@ -696,9 +916,6 @@ dotnet --list-runtimes
 # Restart IIS
 iisreset

-# Verify FFmpeg
-ffmpeg -version
-
 # Test production endpoints
 curl https://tuneripper-api.vrba.one/api/health
 curl -I https://tuneripper.vrba.one
@@ -711,13 +928,66 @@ tasklist | findstr w3wp

 # Check Application Pool status
 %windir%\system32\inetsrv\appcmd.exe list appPools /text:name,state
+```

-# Renew SSL certificates manually
-wacs.exe --renew
-# or
+### Chocolatey Commands
+```powershell
+# Check Chocolatey version
+choco --version
+
+# List installed packages
+choco list --local-only
+
+# Update all packages
+choco upgrade all -y
+
+# Update specific packages
+choco upgrade ffmpeg yt-dlp dotnet-hosting -y
+
+# Check for outdated packages
+choco outdated
+
+# Verify installed tools
+ffmpeg -version
+yt-dlp --version
+```
+
+### SSL Certificate Management
+```cmd
+# win-acme commands (Chocolatey installation)
+wacs --list
+wacs --renew
+
+# win-acme commands (manual installation)
+C:\win-acme\wacs.exe --list
+C:\win-acme\wacs.exe --renew
+
+# certbot commands
+certbot certificates
 certbot renew
 ```

 ---

-*This guide includes production-ready HTTPS setup with Let's Encrypt for the subdomain configuration: `https://tuneripper.vrba.one` and `https://tuneripper-api.vrba.one`. The existing CORS configuration will work without modifications.*
+## Chocolatey Benefits Summary
+
+### ?? **Advantages of Using Chocolatey**
+- **Automated Installation**: No manual downloads or extractions needed
+- **Automatic PATH Configuration**: Tools are immediately available system-wide  
+- **Easy Updates**: Update all tools with a single command
+- **Consistent Environment**: Same setup across multiple machines
+- **Dependency Management**: Automatically handles tool dependencies
+- **Easy Removal**: Clean uninstallation when needed
+- **Version Control**: Pin specific versions if required
+
+### ?? **Packages Used in This Guide**
+- `dotnet-hosting` - .NET 10 Hosting Bundle for IIS
+- `dotnet-sdk` - .NET 10 SDK (development scenario)
+- `ffmpeg` - Audio/video processing library
+- `yt-dlp` - YouTube video downloader
+- `win-acme` - Let's Encrypt SSL certificate management
+- `curl` - HTTP testing utility
+
+---
+
+*This guide includes production-ready HTTPS setup with Let's Encrypt for the subdomain configuration: `https://tuneripper.vrba.one` and `https://tuneripper-api.vrba.one`. The existing CORS configuration will work without modifications. Chocolatey package manager provides automated installation and maintenance for all prerequisites.*