PepApi.Core/scripts/DEPLOY.md

PepApi Deployment Guide

Quick Deployment (Windows Service)

Prerequisites

• .NET 8 Runtime or SDK installed
• Administrator privileges
• Network access to PepDB SQL Server
• Access to nest files directory

Deploy as Windows Service

# Run as Administrator from repository root
powershell -ExecutionPolicy Bypass -File scripts/Deploy-PepApi.ps1 -OpenFirewall

This will:

• Build and publish PepApi.Core in Release mode
• Install to C:\Services\PepApi
• Create Windows Service named "PepApi"
• Configure service to run on port 8085
• Open Windows Firewall for port 8085
• Start the service automatically

By default, the service runs under the current user (you will be prompted for your password). To install as LocalSystem instead, add -UseLocalSystem.

Custom Deployment

# Custom service name and location
powershell -ExecutionPolicy Bypass -File scripts/Deploy-PepApi.ps1 `
  -ServiceName "MyPepApi" `
  -InstallDir "D:\Services\PepApi" `
  -Urls "http://*:9000" `
  -OpenFirewall

Run Service As User (for network access)

By default the service runs under your current user to allow access to network shares. You can also explicitly choose an account:

# Prompt for the current user's password and install the service to run as you
powershell -ExecutionPolicy Bypass -File scripts/Deploy-PepApi.ps1 -RunAsCurrentUser

# Or specify explicit credentials (you will get a secure credential prompt)
$cred = Get-Credential  # Enter DOMAIN\User or .\LocalUser
powershell -ExecutionPolicy Bypass -File scripts/Deploy-PepApi.ps1 -ServiceCredential $cred

# Or pass a domain user and get prompted for its password
powershell -ExecutionPolicy Bypass -File scripts/Deploy-PepApi.ps1 -DomainUser "MYDOMAIN\\jdoe"

# Or pass domain and user separately
powershell -ExecutionPolicy Bypass -File scripts/Deploy-PepApi.ps1 -Domain "MYDOMAIN" -User "jdoe"

### Install As LocalSystem (opt-out of default user)

```powershell
powershell -ExecutionPolicy Bypass -File scripts/Deploy-PepApi.ps1 -UseLocalSystem

Notes:
- The account must have the "Log on as a service" right. Windows typically grants this during service creation.
- Ensure the account has read access to configured network paths in `appsettings.json`.

### Configuration

After deployment, **you must update** `C:\Services\PepApi\appsettings.json`:

```json
{
  "ConnectionStrings": {
    "PepDB": "data source=YOUR_SERVER\\INSTANCE;initial catalog=PEP;integrated security=True;..."
  },
  "PepSettings": {
    "NestDirectory": "\\\\YOUR_SERVER\\PEP Nest",
    "Materials": "Now sourced from database (no file path)"
  }
}

Then restart the service:

Restart-Service -Name PepApi

---

Alternative: Self-Hosted (No Service)

Build and Run

cd PepApi.Core
dotnet publish -c Release -o ./publish
cd publish
.\PepApi.Core.exe

Run with Custom Settings

.\PepApi.Core.exe --urls "http://*:8085"

---

Alternative: IIS Deployment

1. Install Prerequisites

• Install ASP.NET Core Hosting Bundle from Microsoft
• Create IIS Application Pool (No Managed Code)

2. Publish Application

dotnet publish PepApi.Core/PepApi.Core.csproj -c Release -o C:\inetpub\PepApi

3. Configure IIS

• Create new website in IIS Manager
• Point to C:\inetpub\PepApi
• Use Application Pool with "No Managed Code"
• Set binding to port 8085

4. Update Configuration

• Edit C:\inetpub\PepApi\appsettings.json
• Restart IIS site

---

Verify Deployment

Check Service Status

Get-Service -Name PepApi

Test API

# Health check
Invoke-WebRequest http://localhost:8085/swagger

# Test nests endpoint
Invoke-WebRequest http://localhost:8085/nests/2024

View Logs

# Service logs in Event Viewer
Get-EventLog -LogName Application -Source PepApi -Newest 20

# Or check console output if running self-hosted

---

Service Management

Start Service

Start-Service -Name PepApi

Stop Service

Stop-Service -Name PepApi

Restart Service

Restart-Service -Name PepApi

Uninstall Service

Stop-Service -Name PepApi
sc.exe delete PepApi

---

Firewall Configuration

If you didn't use -OpenFirewall during deployment:

# Open port 8085
New-NetFirewallRule -DisplayName "PepApi HTTP 8085" `
  -Direction Inbound `
  -Protocol TCP `
  -LocalPort 8085 `
  -Action Allow

---

Troubleshooting

Service Won't Start

1. Check Event Viewer for errors:

   Get-EventLog -LogName Application -Source PepApi -Newest 10
   

2. Verify configuration:

   • Database connection string is correct
   • Network paths are accessible
   • Files exist at specified paths

3. Test manually:

   cd C:\Services\PepApi
   .\PepApi.Core.exe
   

Database Connection Errors

• Verify SQL Server is accessible
• Check Windows Authentication permissions
• Test connection string with SSMS
• Ensure TrustServerCertificate=True in connection string

File Access Errors

• Verify service account has read access to:
  • Nest directory (\\REMCOSRV0\PEP Nest)
• Configure service to run as appropriate account

Port Already in Use

# Find what's using port 8085
netstat -ano | findstr :8085

# Kill the process
Stop-Process -Id [PID] -Force

# Or deploy on different port
scripts/Deploy-PepApi.ps1 -Urls "http://*:9000"

---

Update/Redeploy

To update the service with new code:

# Simply run the deploy script again
powershell -ExecutionPolicy Bypass -File scripts/Deploy-PepApi.ps1 -OpenFirewall

The script will:

• Stop the existing service
• Deploy the new version
• Restart the service

Note: Your appsettings.json changes will be preserved.

---

API Endpoints

Once deployed, the API will be available at:

• Swagger UI: http://localhost:8085/swagger
• OpenAPI Spec: http://localhost:8085/swagger/v1/swagger.json

Endpoints

• GET /nests/{year} - Get nests for year
• GET /nests/{nestName}?year=YYYY - Get nest (year optional, finds most recent)
• GET /nests/{nestName}/download?year=YYYY - Download nest file
• GET /nests/{nestName}/plates?year=YYYY - Get plates
• GET /materials - Get all materials
• GET /materials/{id} - Get specific material

---

Security Notes

⚠️ Before production deployment:

1. Enable HTTPS (not configured by default)
2. Add authentication/authorization
3. Review CORS policy (currently allows all origins)
4. Update DotNetZip package (has security vulnerability)
5. Run service with least-privilege account

---

Performance Tips

• Consider adding response caching
• Enable response compression in production
• Monitor database query performance
• Add connection pooling configuration if needed

---

Support

For issues:

1. Check Event Viewer logs
2. Review appsettings.json configuration
3. Test database and file access manually
4. Review MIGRATION_SUMMARY.md for detailed changes