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

```powershell
# 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

### Custom Deployment

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

### 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",
    "MaterialsFile": "C:\\Pep\\PEP2012\\CONFIG\\material.lfn"
  }
}
```

Then restart the service:
```powershell
Restart-Service -Name PepApi
```

---

## Alternative: Self-Hosted (No Service)

### Build and Run

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

### Run with Custom Settings

```bash
.\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

```bash
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
```powershell
Get-Service -Name PepApi
```

### Test API
```powershell
# Health check
Invoke-WebRequest http://localhost:8085/swagger

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

### View Logs
```powershell
# 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
```powershell
Start-Service -Name PepApi
```

### Stop Service
```powershell
Stop-Service -Name PepApi
```

### Restart Service
```powershell
Restart-Service -Name PepApi
```

### Uninstall Service
```powershell
Stop-Service -Name PepApi
sc.exe delete PepApi
```

---

## Firewall Configuration

If you didn't use `-OpenFirewall` during deployment:

```powershell
# 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:
   ```powershell
   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:
   ```bash
   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`)
  - Materials file (`C:\Pep\PEP2012\CONFIG\material.lfn`)
- Configure service to run as appropriate account

### Port Already in Use

```powershell
# 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:

```powershell
# 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