Detailed Setup Guide¶

Home → Documentation → Setup → Detailed Setup

This comprehensive guide covers all aspects of installing, configuring, and verifying Cesivi Server.

Table of Contents¶

Prerequisites
Installation Methods
Initial Configuration
Verification Steps
Common Setup Issues
Production Considerations
Next Steps

Prerequisites¶

Required Components¶

1. .NET 10.0 SDK¶

Download: dotnet.microsoft.com/download

Verify installation:

dotnet --version
# Expected: 10.0.x or higher

Supported Platforms: - Windows 10/11 (x64, ARM64) - Windows Server 2016+ (x64) - Linux (Ubuntu 22.04+, Debian 11+, RHEL 8+, Alpine 3.17+) - macOS 12+ (x64, ARM64/Apple Silicon)

2. System Requirements¶

Component	Minimum	Recommended
CPU	1 core	2+ cores
RAM	512 MB	2 GB
Disk Space	500 MB	2 GB+ (includes MockData)
Network	Available port	Firewall configured

3. Optional Components¶

Component	Purpose	Required For
Docker	Container deployment	Production, CI/CD
Git	Source code checkout	Development
PowerShell 7+	PnP PowerShell testing	PnP integration
Visual Studio 2022	Development/debugging	Code changes

Environment Verification¶

Run these commands to verify your environment:

# .NET SDK
dotnet --version
dotnet --list-sdks
dotnet --list-runtimes

# Verify .NET 10.0 is present
dotnet --list-runtimes | Select-String "Microsoft.AspNetCore.App 10.0"

# Optional: Docker
docker --version
docker-compose --version

# Optional: PowerShell
$PSVersionTable.PSVersion

Installation Methods¶

Method 1: Install from Source (Development)¶

Best for: Development, customization, contribution

Step 1: Clone Repository¶

# HTTPS
git clone https://github.com/your-org/Cesivi.git
cd Cesivi

# SSH (requires GitHub SSH key)
git clone git@github.com:your-org/Cesivi.git
cd Cesivi

# Verify
git branch
# Expected: * main (or your default branch)

Step 2: Build Solution¶

# Clean any previous builds
dotnet clean

# Restore dependencies
dotnet restore

# Build all projects
dotnet build --configuration Release

# Expected output:
# Build succeeded.
#     0 Warning(s)
#     0 Error(s)

Step 3: Run Server¶

cd Cesivi.Server
dotnet run --configuration Release

# Server will output:
# info: Microsoft.Hosting.Lifetime[14]
#       Now listening on: http://localhost:5000
#       Application started. Press Ctrl+C to shut down.

Step 4: Verify (in new terminal)¶

curl http://localhost:5000/_vti_bin/health

# Expected JSON response:
# {
#   "status": "Healthy",
#   "uptime": {...},
#   "requests": {...}
# }

Method 2: Docker Container (Production)¶

Best for: Production, CI/CD, isolated environments

See Docker Deployment Guide for complete Docker setup.

Quick Docker Setup:

# Using Docker Compose (recommended)
docker-compose up -d

# Verify
curl http://localhost:8080/_vti_bin/health

Method 3: Published Binary (Deployment)¶

Best for: Deployment to servers without build tools

Step 1: Publish Application¶

# Self-contained (no .NET runtime required on target)
dotnet publish Cesivi.Server/Cesivi.Server.csproj \
  --configuration Release \
  --runtime win-x64 \
  --self-contained true \
  --output ./publish/win-x64

# Framework-dependent (requires .NET 10.0 runtime on target)
dotnet publish Cesivi.Server/Cesivi.Server.csproj \
  --configuration Release \
  --self-contained false \
  --output ./publish/portable

Runtimes: - win-x64 - Windows 64-bit - linux-x64 - Linux 64-bit - osx-x64 - macOS Intel - osx-arm64 - macOS Apple Silicon

Step 2: Copy to Deployment Location¶

# Windows
Copy-Item -Recurse ./publish/win-x64 C:\Cesivi\

# Linux
cp -r ./publish/linux-x64 /opt/Cesivi/

Step 3: Run Published Binary¶

# Windows (self-contained)
C:\Cesivi\Cesivi.Server.exe

# Linux (self-contained)
/opt/Cesivi/Cesivi.Server

# Framework-dependent
dotnet Cesivi.Server.dll

Initial Configuration¶

1. Configure Ports¶

Default Ports: - HTTP: 5000 - HTTPS: 5001

Change Ports via Environment Variables:

# Windows PowerShell
$env:ASPNETCORE_URLS = "http://localhost:8080"

# Linux/macOS Bash
export ASPNETCORE_URLS=http://localhost:8080

# Both protocols
$env:ASPNETCORE_URLS = "http://localhost:8080;https://localhost:8443"

Change Ports via appsettings.json:

Edit Cesivi.Server/appsettings.json:

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

2. Configure MockData Path¶

Default: ./MockData (relative to server executable)

Change via Environment Variable:

# Windows
$env:Cesivi__DataRootPath = "C:\Data\Cesivi"

# Linux
export Cesivi__DataRootPath=/var/lib/Cesivi/data

Change via appsettings.json:

{
  "Cesivi": {
    "DataRootPath": "C:\\Data\\Cesivi",
    "AutoInitialize": true
  }
}

See Configuration Guide for complete configuration options.

3. Configure Logging¶

Set Log Level:

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Cesivi": "Debug"
    }
  }
}

Log Levels: - Trace - Very verbose (every detail) - Debug - Debugging information - Information - General information (default) - Warning - Warnings - Error - Errors only - Critical - Critical errors only

4. Configure Performance¶

{
  "Cesivi": {
    "Performance": {
      "CacheEnabled": true,
      "CacheDurationMinutes": 15,
      "MaxConcurrentRequests": 100
    }
  }
}

Verification Steps¶

1. Check Server Health¶

# Basic health check (no auth required)
curl http://localhost:5000/_vti_bin/health

# Expected response:
{
  "status": "Healthy",
  "uptime": {
    "seconds": 30,
    "formatted": "00:00:30"
  },
  "requests": {
    "total": 1,
    "successful": 1,
    "failed": 0,
    "errorRate": "0.00%"
  },
  "timestamp": "2025-11-15T10:30:00Z"
}

2. Test REST API¶

# Get web information
curl http://localhost:5000/_api/web

# Expected response (abbreviated):
{
  "d": {
    "__metadata": {
      "type": "SP.Web"
    },
    "Title": "Default Web",
    "Url": "http://localhost:5000",
    "Description": "Default Cesivi Web"
  }
}

3. Test SOAP Services¶

# Test GetWeb SOAP endpoint
$soapEnvelope = @"
<?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>
"@

$response = Invoke-WebRequest `
  -Uri "http://localhost:5000/_vti_bin/webs.asmx" `
  -Method Post `
  -ContentType "text/xml; charset=utf-8" `
  -Body $soapEnvelope

$response.Content

4. Test Authentication¶

# With Basic authentication
curl -u admin:password http://localhost:5000/_api/web

# With Bearer token
curl -H "Authorization: Bearer test-token" http://localhost:5000/_api/web

Note: Mock server accepts any credentials by default for testing. Configure real authentication in production.

5. Test CSOM Integration¶

Create a test C# console application:

using Microsoft.SharePoint.Client;
using System;

class Program
{
    static void Main()
    {
        using (var ctx = new ClientContext("http://localhost:5000"))
        {
            ctx.Credentials = new System.Net.NetworkCredential("admin", "password");

            var web = ctx.Web;
            ctx.Load(web);
            ctx.ExecuteQuery();

            Console.WriteLine($"Web Title: {web.Title}");
            Console.WriteLine($"Web URL: {web.Url}");
        }
    }
}

6. Test PnP PowerShell¶

# Import PnP module (adjust path as needed)
Import-Module SharePointPnPPowerShellOnline

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

# Get web info
$web = Get-PnPWeb
Write-Host "Web Title: $($web.Title)"

# Get lists
$lists = Get-PnPList
Write-Host "Lists: $($lists.Count)"

# Disconnect
Disconnect-PnPOnline

Common Setup Issues¶

Issue 1: Port Already in Use¶

Symptoms:

Error: Address already in use
Unable to bind to http://localhost:5000

Solution:

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

# Kill the process (Windows)
taskkill /PID <PID> /F

# Or use a different port
$env:ASPNETCORE_URLS = "http://localhost:8080"
dotnet run

Issue 2: .NET SDK Not Found¶

Symptoms:

The command 'dotnet' could not be found

Solution:

Download .NET 10.0 SDK from dotnet.microsoft.com
Install and restart terminal
Verify: dotnet --version

Issue 3: Build Errors¶

Symptoms:

Build FAILED
error CS0006: Metadata file '...' could not be found

Solution:

# Clean all build artifacts
dotnet clean

# Restore NuGet packages
dotnet restore

# Build again
dotnet build --configuration Release

Issue 4: MockData Permission Denied¶

Symptoms:

System.UnauthorizedAccessException: Access to path 'MockData' is denied

Solution:

# Windows: Grant permissions
icacls MockData /grant Users:F /T

# Linux: Fix ownership
sudo chown -R $USER:$USER ./MockData

# Or use a different path
$env:Cesivi__DataRootPath = "$env:TEMP\Cesivi"

Issue 5: SSL Certificate Errors¶

Symptoms:

The SSL connection could not be established

Solution:

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

# Or use HTTP only (for development)
$env:ASPNETCORE_URLS = "http://localhost:5000"

Issue 6: Firewall Blocking Connections¶

Symptoms: - Server starts but can't connect from another machine - Connection timeout errors

Solution:

# Windows: Add firewall rule
New-NetFirewallRule -DisplayName "Cesivi HTTP" -Direction Inbound -Protocol TCP -LocalPort 5000 -Action Allow

# Linux: Allow port in firewall
sudo ufw allow 5000/tcp

# Verify server is listening on all interfaces
$env:ASPNETCORE_URLS = "http://0.0.0.0:5000"

Production Considerations¶

1. Security Hardening¶

DO: - ✅ Use HTTPS with valid certificates - ✅ Implement proper authentication - ✅ Restrict network access (firewall rules) - ✅ Run as non-root user (Linux) - ✅ Use environment variables for secrets

DON'T: - ❌ Accept any credentials (configure real auth) - ❌ Expose diagnostics endpoint publicly - ❌ Store secrets in appsettings.json - ❌ Run with unnecessary permissions

2. Performance Optimization¶

{
  "Cesivi": {
    "Performance": {
      "CacheEnabled": true,
      "CacheDurationMinutes": 30,
      "MaxConcurrentRequests": 200
    }
  }
}

3. Logging for Production¶

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning",
      "Microsoft.AspNetCore": "Error",
      "Cesivi": "Information"
    }
  }
}

4. Data Backup Strategy¶

# Automated backup script
$timestamp = Get-Date -Format "yyyyMMdd_HHmmss"
$backupPath = "C:\Backups\Cesivi_$timestamp"

# Stop server
Stop-Service CesiviServer

# Backup MockData
Copy-Item -Recurse "C:\Cesivi\MockData" $backupPath

# Start server
Start-Service CesiviServer

# Cleanup old backups (keep last 7 days)
Get-ChildItem "C:\Backups" -Filter "Cesivi_*" |
  Where-Object { $_.LastWriteTime -lt (Get-Date).AddDays(-7) } |
  Remove-Item -Recurse -Force

5. Monitoring & Alerting¶

Health Check Monitoring:

# Add to cron/Task Scheduler
curl http://localhost:5000/_vti_bin/health | jq '.status'
# Alert if not "Healthy"

Log Monitoring:

# Monitor error logs
tail -f /var/log/Cesivi/errors.log | grep "ERROR"

Next Steps¶

For Development¶

Learn the APIs → REST API Guide
Try examples → Basic Operations
Understand limitations → Known Limitations

For Production¶

Deploy with Docker → Docker Deployment Guide
Configure for production → Configuration Guide
Set up monitoring → Troubleshooting Guide

For Testing¶

Import test data → Migration Tool Guide
Run tests → Testing Guide
Create plugins → Plugin Guide

Support Resources¶

Configuration Questions → Configuration Guide
Troubleshooting → General Troubleshooting
Docker Issues → Docker Troubleshooting
Feature Questions → Features Overview
API Reference → API Reference

Post-Setup Checklist¶

[ ] Server starts without errors
[ ] Health endpoint responds with "Healthy"
[ ] REST API returns valid JSON
[ ] SOAP services respond to requests
[ ] CSOM connection successful (if using CSOM)
[ ] PnP PowerShell connects (if using PnP)
[ ] MockData directory created and writable
[ ] Ports accessible (no firewall blocking)
[ ] Logging configured appropriately
[ ] Backup strategy in place (production only)

← Back to Setup | Next: Configuration → | View All Docs