Cesivi Server - Deployment Guide

Overview

The Cesivi Server is a production-ready ASP.NET Core application that provides a complete SharePoint API mock implementation. This guide covers deployment options, configuration, and operational procedures.

Prerequisites

System Requirements

• .NET 10 SDK (or later)
• Operating System: Windows, Linux, or macOS
• Memory: Minimum 512MB RAM, recommended 2GB for production workloads
• Disk Space: Minimum 500MB for application + MockData storage
• Network: Available HTTP port (default: 5000) or HTTPS port (default: 5001)

Optional Requirements

• Docker (for containerized deployment)
• Reverse Proxy (nginx, IIS, or Apache for production)
• Monitoring Tools (Prometheus/Grafana for observability)

Installation Methods

Method 1: Direct Deployment (Development/Testing)

# Clone the repository
git clone <repository-url>
cd Cesivi

# Build the application
dotnet clean
dotnet build --configuration Release

# Run the server
cd Cesivi.Server
dotnet run --configuration Release

Server will start on: - HTTP: http://localhost:5000 - HTTPS: https://localhost:5001

Method 2: Published Deployment (Production)

# Publish the application
dotnet publish Cesivi.Server/Cesivi.Server.csproj `
  --configuration Release `
  --output ./publish `
  --self-contained false

# Copy published files to deployment location
Copy-Item -Recurse ./publish C:\Cesivi\

# Run the published application
cd C:\Cesivi
dotnet Cesivi.Server.dll

Method 3: Windows Service (Production)

# Publish as Windows Service
dotnet publish Cesivi.Server/Cesivi.Server.csproj `
  --configuration Release `
  --runtime win-x64 `
  --self-contained true `
  --output C:\Cesivi

# Install as Windows Service (requires administrator)
sc create "CesiviServer" binPath= "C:\Cesivi\Cesivi.Server.exe"
sc description "CesiviServer" "Cesivi Server for API testing"
sc config "CesiviServer" start= auto

# Start the service
sc start "CesiviServer"

# Check service status
sc query "CesiviServer"

Method 4: Linux systemd Service

# Publish for Linux
dotnet publish Cesivi.Server/Cesivi.Server.csproj \
  --configuration Release \
  --runtime linux-x64 \
  --self-contained true \
  --output /opt/Cesivi

# Create systemd service file
sudo cat > /etc/systemd/system/Cesivi.service <<EOF
[Unit]
Description=Cesivi Server
After=network.target

[Service]
Type=notify
WorkingDirectory=/opt/Cesivi
ExecStart=/opt/Cesivi/Cesivi.Server
Restart=always
RestartSec=10
User=www-data
Environment=ASPNETCORE_ENVIRONMENT=Production
Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false

[Install]
WantedBy=multi-user.target
EOF

# Enable and start the service
sudo systemctl daemon-reload
sudo systemctl enable Cesivi
sudo systemctl start Cesivi

# Check status
sudo systemctl status Cesivi

Method 5: Docker Container (Recommended for Production)

Cesivi Server includes a production-ready Dockerfile with: - Multi-stage build for optimized image size - Non-root user for security - Health checks - Volume mapping for persistent MockData

Using Docker Compose (Recommended)

# Start the container
docker-compose up -d

# Check container status
docker-compose ps

# View logs
docker-compose logs -f

# Stop the container
docker-compose down

Using Docker CLI

# Build Docker image
docker build -t Cesivi:latest .

# Run container with volume mapping
docker run -d \
  --name cesivi-server \
  --hostname mocksharepoint.local \
  -p 8080:8080 \
  -e ASPNETCORE_ENVIRONMENT=Production \
  -e Cesivi__DataRootPath=/app/MockData \
  -e Cesivi__HostName=mocksharepoint.local \
  -v ./MockData:/app/MockData \
  -v ./logs:/app/logs \
  Cesivi:latest

# Check container status
docker ps

# View logs
docker logs -f cesivi-server

# Check health
docker inspect cesivi-server | grep Health -A 10

Rebuild Container After Code Changes

# Stop and remove existing container
docker-compose down

# Rebuild image (no cache)
docker-compose build --no-cache

# Start new container
docker-compose up -d

# Verify
curl http://localhost:8080/

Configuration

Application Settings

Edit appsettings.json or create appsettings.Production.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "MockData": {
    "BasePath": "@MockData",
    "AutoInitialize": true
  },
  "Performance": {
    "CacheEnabled": true,
    "CacheDurationMinutes": 15
  },
  "Urls": "http://localhost:5000;https://localhost:5001"
}

Environment Variables

Override configuration using environment variables:

# Windows PowerShell
$env:ASPNETCORE_ENVIRONMENT = "Production"
$env:ASPNETCORE_URLS = "http://localhost:8080"
$env:MockData__BasePath = "C:\Data\Cesivi"
$env:Performance__CacheEnabled = "true"

# Linux/macOS Bash
export ASPNETCORE_ENVIRONMENT=Production
export ASPNETCORE_URLS=http://localhost:8080
export MockData__BasePath=/data/Cesivi
export Performance__CacheEnabled=true

Port Configuration

Change listening ports:

1. Via appsettings.json:

   {
     "Urls": "http://0.0.0.0:8080;https://0.0.0.0:8443"
   }
   

2. Via command line:

   dotnet Cesivi.Server.dll --urls "http://0.0.0.0:8080"
   

3. Via environment variable:

   $env:ASPNETCORE_URLS = "http://0.0.0.0:8080"
   dotnet Cesivi.Server.dll
   

SSL/TLS Configuration

Option 1: Development Certificate

# Trust development certificate
dotnet dev-certs https --trust

# Server runs on https://localhost:5001
dotnet run

Option 2: Production Certificate

{
  "Kestrel": {
    "Endpoints": {
      "Https": {
        "Url": "https://*:443",
        "Certificate": {
          "Path": "/path/to/certificate.pfx",
          "Password": "certificate-password"
        }
      }
    }
  }
}

Option 3: Reverse Proxy (Recommended)

Use nginx or IIS to handle SSL termination:

# nginx configuration
server {
    listen 443 ssl;
    server_name mocksharepoint.local;

    ssl_certificate /etc/nginx/ssl/cert.pem;
    ssl_certificate_key /etc/nginx/ssl/key.pem;

    location / {
        proxy_pass http://localhost:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection keep-alive;
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Data Storage

MockData Directory Structure

The server stores all data in the @MockData directory:

@MockData/
├── Farm/
│   ├── settings.json
│   ├── GlobalTermStore/
│   └── SearchIndex/
├── WebApplications/
│   └── Default/
│       └── SiteCollections/
│           └── RootSite/
│               ├── settings.json
│               ├── Users/
│               ├── Groups/
│               └── RootWeb/
│                   ├── settings.json
│                   ├── Lists/
│                   ├── Libraries/
│                   └── ContentTypes/
└── Logs/
    └── Proxy/

Backup and Restore

Backup MockData:

# Stop the server first
Stop-Service "CesiviServer"

# Backup data directory
$timestamp = Get-Date -Format "yyyyMMdd_HHmmss"
Copy-Item -Recurse "@MockData" "backups\MockData_$timestamp"

# Restart server
Start-Service "CesiviServer"

Restore from Backup:

# Stop server
Stop-Service "CesiviServer"

# Restore data
Remove-Item -Recurse "@MockData"
Copy-Item -Recurse "backups\MockData_20251004_120000" "@MockData"

# Restart server
Start-Service "CesiviServer"

Data Migration

Export data for migration:

# Compress MockData for transfer
Compress-Archive -Path "@MockData" -DestinationPath "mockdata_export.zip"

Import on new server:

# Extract MockData
Expand-Archive -Path "mockdata_export.zip" -DestinationPath "."

Health Monitoring

Health Check Endpoints

Public Health Check (no authentication):

# Check server health
Invoke-RestMethod -Uri "http://localhost:5000/_vti_bin/health" -Method Get

# Expected response:
{
  "status": "Healthy",
  "uptime": { "seconds": 3600, "formatted": "01:00:00" },
  "requests": {
    "total": 150,
    "successful": 145,
    "failed": 5,
    "errorRate": "3.33%"
  },
  "timestamp": "2025-10-04T23:00:00Z"
}

Diagnostics Endpoint (requires authentication):

$creds = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes("user:pass"))
Invoke-RestMethod `
  -Uri "http://localhost:5000/_vti_bin/diagnostics" `
  -Method Get `
  -Headers @{"Authorization" = "Basic $creds"}

# Detailed metrics including performance, cache stats, etc.

Load Balancer Integration

Health check configuration for load balancers: - Endpoint: GET /_vti_bin/health - Expected Status: 200 OK - Interval: 30 seconds - Timeout: 5 seconds - Unhealthy Threshold: 3 consecutive failures

Logging

Log locations: - Console: Real-time output (stdout/stderr) - Application Insights: Configure via appsettings.json (optional) - File Logging: Add Serilog or NLog (optional)

Correlation ID Tracking: Every response includes correlation headers: - X-Correlation-ID: Unique request identifier - SPRequestGuid: SharePoint-compatible request GUID - SPRequestDuration: Request processing time (ms)

Testing the Deployment

Quick Validation

# 1. Check health endpoint
$health = Invoke-RestMethod -Uri "http://localhost:5000/_vti_bin/health"
Write-Host "Server Status: $($health.status)"

# 2. Test authentication
$creds = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes("test:test"))
$headers = @{"Authorization" = "Basic $creds"}

# 3. Test SOAP endpoint
$soapXml = @"
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Body>
    <GetWeb xmlns="http://schemas.microsoft.com/sharepoint/soap/">
      <webUrl>/</webUrl>
    </GetWeb>
  </soap:Body>
</soap:Envelope>
"@

$headers["Content-Type"] = "text/xml; charset=utf-8"
Invoke-WebRequest `
  -Uri "http://localhost:5000/_vti_bin/webs.asmx" `
  -Method Post `
  -Headers $headers `
  -Body $soapXml

# 4. Test REST endpoint
Invoke-RestMethod `
  -Uri "http://localhost:5000/_api/web" `
  -Method Get `
  -Headers @{"Authorization" = "Basic $creds"}

PnP PowerShell Integration

# Import PnP module
Import-Module SharePointPnPPowerShell2019

# Connect to mock server
Connect-PnPOnline `
  -Url "http://localhost:5000" `
  -Credentials (Get-Credential)

# Test basic operations
Get-PnPWeb
Get-PnPList
Get-PnPUser

Troubleshooting

Common Issues

Port already in use:

# Find process using port 5000
netstat -ano | findstr :5000

# Kill process (replace PID)
taskkill /PID <PID> /F

# Or use different port
dotnet run --urls "http://localhost:8080"

MockData permission errors:

# Windows: Grant full control
icacls "@MockData" /grant Users:F /T

# Linux: Fix ownership
sudo chown -R www-data:www-data /opt/Cesivi/@MockData

High memory usage: - Check @MockData size (large datasets increase memory) - Adjust cache settings in appsettings.json - Increase server memory allocation

Slow response times: - Check diagnostics endpoint for performance metrics - Review cache hit rates (target >70%) - Consider database storage instead of file system for large datasets

Production Best Practices

Security

1. Disable automatic authentication acceptance (production should validate credentials)
2. Use HTTPS only (enforce SSL/TLS)
3. Implement rate limiting (protect against abuse)
4. Restrict diagnostics endpoint (internal networks only)
5. Audit log access (track who queries sensitive data)

Performance

1. Enable caching (Performance:CacheEnabled = true)
2. Use SSD storage for @MockData directory
3. Configure reverse proxy (nginx/IIS for load balancing)
4. Monitor P95/P99 response times (target <500ms)
5. Implement CDN for static content (if applicable)

Reliability

1. Automated backups (daily @MockData snapshots)
2. Health check monitoring (alerting on failures)
3. Graceful degradation (return cached data if storage unavailable)
4. Circuit breakers (protect against cascading failures)
5. Logging and alerting (centralized log aggregation)

Scalability

1. Horizontal scaling (multiple instances behind load balancer)
2. Database backend (consider SQL Server/PostgreSQL for large datasets)
3. Redis caching (shared cache across instances)
4. Message queue (async processing for write-heavy workloads)
5. Read replicas (separate instances for read operations)

Support and Maintenance

Updates

# Pull latest changes
git pull origin main

# Rebuild
dotnet clean
dotnet build --configuration Release

# Restart service
Restart-Service "CesiviServer"

Monitoring Checklist

• [ ] Health endpoint responding (200 OK)
• [ ] Error rate <5%
• [ ] P95 response time <500ms
• [ ] Cache hit rate >70%
• [ ] Disk space >10% free
• [ ] Memory usage <80%
• [ ] CPU usage <70%

Contact and Resources

• Documentation: See _docs/ directory for additional guides
• API Reference: _docs/API_REFERENCE.md
• Troubleshooting: _docs/TROUBLESHOOTING.md
• GitHub Issues: Report bugs and feature requests
• Community: SharePoint developer forums

---

Deployment Guide Version: 1.0 Last Updated: 2025-10-04 Compatible with: Cesivi Server v1.0+ (.NET 10)