From e361f26cdf430ae3a6abfffa86caaaf0ab381021 Mon Sep 17 00:00:00 2001 From: Michal Vrba Date: Sun, 14 Dec 2025 12:15:26 +0100 Subject: [PATCH] doc updated --- DEPLOYMENT_GUIDE_IIS_Windows11.md | 332 +++++++++++++++++++++++++++--- 1 file changed, 301 insertions(+), 31 deletions(-) diff --git a/DEPLOYMENT_GUIDE_IIS_Windows11.md b/DEPLOYMENT_GUIDE_IIS_Windows11.md index f464b28..b0e1bb4 100644 --- a/DEPLOYMENT_GUIDE_IIS_Windows11.md +++ b/DEPLOYMENT_GUIDE_IIS_Windows11.md @@ -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 -y + choco install -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.* \ No newline at end of file +## 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.* \ No newline at end of file