Configuration Guide¶

Home → Documentation → Setup → Configuration

Comprehensive guide to configuring Cesivi Server for development, testing, and production environments.

Table of Contents¶

Quick Reference
Environment Variables
appsettings.json Configuration
MockData Configuration
Branch Configuration
Port Configuration
SSL/TLS Configuration
Multi-Instance Scenarios
Configuration Priority
Custom Configuration Files

Quick Reference¶

Common Configuration Methods¶

Method	Use Case	Persistent	Priority
Environment Variables	CI/CD, Docker, multi-instance	No	High
appsettings.json	Single instance, development	Yes	Medium
Command-line Arguments	Testing, one-off runs	No	Highest
Custom Config File	Production, Docker, deployment	Yes	Configurable
.env File	Test scripts	No	Via env vars
Branch Config	Multi-worktree development	Yes	Via env vars

Key Configuration Files¶

File	Location	Purpose	Committed?
`appsettings.json`	`Cesivi.Server/`	Server configuration	✅ Yes
`appsettings.Production.json`	`Cesivi.Server/`	Production overrides	✅ Yes
`.env`	`test-scripts/`	Test environment	❌ No (.gitignore)
`.env.template`	`test-scripts/`	Test template	✅ Yes
`.branch-config.json`	Repository root	Branch-specific ports	✅ Yes
`launchSettings.json`	`Cesivi.Server/Properties/`	Visual Studio	❌ No (generated)

Environment Variables¶

ASP.NET Core Variables¶

# Environment (Development, Staging, Production)
ASPNETCORE_ENVIRONMENT=Production

# Listening URLs
ASPNETCORE_URLS=http://localhost:5000;https://localhost:5001

# Disable telemetry
DOTNET_PRINT_TELEMETRY_MESSAGE=false

Cesivi Variables¶

# MockData storage path
CESIVI__DataRootPath=/var/lib/Cesivi/data

# Log file path
CESIVI__LogPath=/var/log/Cesivi

# Server hostname
CESIVI__HostName=mocksharepoint.local

# HTTP/HTTPS ports
CESIVI__HttpPort=5000
CESIVI__HttpsPort=5001

# Performance tuning
CESIVI__Performance__CacheEnabled=true
CESIVI__Performance__CacheDurationMinutes=30

Setting Environment Variables¶

Windows PowerShell:

# Current session
$env:CESIVI__DataRootPath = "C:\Data\Cesivi"
$env:ASPNETCORE_ENVIRONMENT = "Production"

# Permanent (user)
[System.Environment]::SetEnvironmentVariable(
  "CESIVI__DataRootPath",
  "C:\Data\Cesivi",
  [System.EnvironmentVariableTarget]::User
)

# Permanent (system - requires admin)
[System.Environment]::SetEnvironmentVariable(
  "CESIVI__DataRootPath",
  "C:\Data\Cesivi",
  [System.EnvironmentVariableTarget]::Machine
)

Linux/macOS Bash:

# Current session
export CESIVI__DataRootPath=/var/lib/Cesivi/data
export ASPNETCORE_ENVIRONMENT=Production

# Permanent (add to ~/.bashrc or ~/.profile)
echo 'export CESIVI__DataRootPath=/var/lib/Cesivi/data' >> ~/.bashrc
source ~/.bashrc

Docker:

# docker-compose.yml
services:
  cesivi:
    environment:
      - CESIVI__DataRootPath=/app/MockData
      - ASPNETCORE_ENVIRONMENT=Production

Verify Environment Variables¶

# Windows
Get-ChildItem Env: | Where-Object { $_.Name -like "*SharePoint*" }

# Linux/macOS
env | grep SharePoint

appsettings.json Configuration¶

Default Configuration¶

Location: Cesivi.Server/appsettings.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Cesivi": {
    "DataRootPath": "./MockData",
    "LogPath": "./MockData/Logs/Server",
    "HostName": "localhost",
    "HttpPort": 5000,
    "HttpsPort": 5001,
    "AutoInitialize": true,
    "Performance": {
      "CacheEnabled": true,
      "CacheDurationMinutes": 15,
      "MaxConcurrentRequests": 100
    }
  },
  "Urls": "http://localhost:5000;https://localhost:5001"
}

Environment-Specific Configuration¶

Create appsettings.Production.json:

{
  "Logging": {
    "LogLevel": {
      "Default": "Warning",
      "Microsoft.AspNetCore": "Error",
      "Cesivi": "Information"
    }
  },
  "Cesivi": {
    "DataRootPath": "/var/lib/Cesivi/data",
    "LogPath": "/var/log/Cesivi",
    "Performance": {
      "CacheEnabled": true,
      "CacheDurationMinutes": 30,
      "MaxConcurrentRequests": 200
    }
  }
}

The environment-specific file overrides appsettings.json values.

Configuration Sections¶

Logging Configuration¶

{
  "Logging": {
    "LogLevel": {
      "Default": "Information",           // General log level
      "Microsoft": "Warning",             // Microsoft framework logs
      "Microsoft.AspNetCore": "Warning",  // ASP.NET Core logs
      "Microsoft.Hosting.Lifetime": "Information",  // Startup/shutdown
      "Cesivi": "Debug"           // Cesivi logs
    }
  }
}

Log Levels: - Trace - Very detailed (every step) - Debug - Debugging information - Information - General information (default) - Warning - Warnings - Error - Errors only - Critical - Critical errors only - None - Disable logging

Cesivi Configuration¶

{
  "Cesivi": {
    // Data storage
    "DataRootPath": "./MockData",
    "LogPath": "./MockData/Logs/Server",
    "AutoInitialize": true,  // Create default data on startup

    // Server identity
    "HostName": "localhost",
    "HttpPort": 5000,
    "HttpsPort": 5001,

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

    // Authentication
    "Authentication": {
      "AcceptAllCredentials": true,  // Development only!
      "RequireHttps": false          // Set true in production
    }
  }
}

MockData Configuration¶

Default Path¶

Relative: ./MockData (relative to server executable)
Absolute: Any valid filesystem path

MockData Directory Structure¶

MockData/
├── WebApplications/
│   └── SharePoint-80/
│       └── SiteCollections/
│           └── root/
│               ├── settings.json
│               ├── Lists/
│               ├── Libraries/
│               └── Users/
├── AD/
│   ├── Users/
│   └── Groups/
├── TermStore/
└── Logs/
    └── Server/

Configure MockData Path¶

Method 1: Environment Variable (Recommended)

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

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

Method 2: appsettings.json

{
  "Cesivi": {
    "DataRootPath": "C:\\Data\\Cesivi"  // Note: escaped backslashes
  }
}

Method 3: Command-line

dotnet run --Cesivi:DataRootPath="C:\Data\Cesivi"

Multi-Worktree MockData Isolation¶

Scenario: Multiple git worktrees, each with own data.

Worktree 1 (main branch - Port 5000):

$env:CESIVI__DataRootPath = "C:\MockData\Main"
$env:CESIVI__HttpPort = 5000

Worktree 2 (feature branch - Port 5010):

$env:CESIVI__DataRootPath = "C:\MockData\Feature"
$env:CESIVI__HttpPort = 5010

Benefits: - ✅ Isolated data per branch - ✅ No data conflicts - ✅ Can run simultaneously - ✅ Independent testing

MockData Backup and Restore¶

Backup:

# Create timestamped backup
$timestamp = Get-Date -Format "yyyyMMdd_HHmmss"
Compress-Archive -Path "./MockData" -DestinationPath "backups/MockData_$timestamp.zip"

Restore:

# Extract backup
Expand-Archive -Path "backups/MockData_20251115_120000.zip" -DestinationPath "./" -Force

Branch Configuration (Multi-Worktree)¶

Overview¶

Branch configuration enables running multiple worktrees with different ports and isolated data.

Configuration File¶

File: .branch-config.json (repository root)

{
  "defaultBranch": "main",
  "branches": {
    "main": {
      "httpPort": 5000,
      "httpsPort": 5001,
      "dataPath": "./MockData",
      "logPath": "./MockData/Logs/Server",
      "hostname": "localhost"
    },
    "main2": {
      "httpPort": 5010,
      "httpsPort": 5011,
      "dataPath": "./MockData",
      "logPath": "./MockData/Logs/Server",
      "hostname": "localhost"
    },
    "feature-x": {
      "httpPort": 5020,
      "httpsPort": 5021,
      "dataPath": "./MockData",
      "logPath": "./MockData/Logs/Server",
      "hostname": "localhost"
    }
  },
  "fallbackConfig": {
    "httpPort": 5000,
    "httpsPort": 5001,
    "dataPath": "./MockData",
    "logPath": "./MockData/Logs/Server",
    "hostname": "localhost"
  }
}

Using Branch Configuration¶

PowerShell Helper:

# Load configuration module
. ".\Scripts\Get-BranchConfig.ps1"

# Get current branch configuration
$config = Get-BranchConfig
Write-Host "HTTP Port: $($config.httpPort)"
Write-Host "Data Path: $($config.dataPath)"

# Set environment variables from config
Set-BranchEnvironment

Automated Setup (Git Hook):

# Install post-checkout hook (one-time)
.\Scripts\Install-GitHooks.ps1

# Automatically updates launchSettings.json on branch switch!

Manual Update:

# Update Visual Studio launch settings
.\Scripts\Update-LaunchSettings.ps1 -Force

Multi-Worktree Example¶

C:\Source\_AI\Cesivi-main (main branch)
├── .branch-config.json (httpPort: 5000)
└── MockData/

C:\Source\_AI\Cesivi-feature (feature-x branch)
├── .branch-config.json (httpPort: 5020)
└── MockData/

Both servers run simultaneously without conflicts!

Port Configuration¶

Default Ports¶

Protocol	Default	Environment Variable
HTTP	5000	`CESIVI__HttpPort`
HTTPS	5001	`CESIVI__HttpsPort`

Change Ports¶

Method 1: Environment Variable

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

Method 2: appsettings.json

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

Method 3: Command-line

dotnet run --urls "http://localhost:8080;https://localhost:8443"

Method 4: Branch Configuration

{
  "branches": {
    "main": {
      "httpPort": 8080,
      "httpsPort": 8443
    }
  }
}

Listen on All Interfaces¶

# Listen on all network interfaces (0.0.0.0)
dotnet run --urls "http://0.0.0.0:5000"

# Or via environment
$env:ASPNETCORE_URLS = "http://0.0.0.0:5000"

⚠️ Security Warning: Only use 0.0.0.0 in trusted networks or with proper firewall rules.

SSL/TLS Configuration¶

Development Certificate¶

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

# Verify
dotnet dev-certs https --check

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

Production Certificate¶

Option 1: appsettings.json

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

Option 2: Environment Variables

export ASPNETCORE_Kestrel__Certificates__Default__Path=/path/to/cert.pfx
export ASPNETCORE_Kestrel__Certificates__Default__Password=cert-password

Option 3: Reverse Proxy (Recommended)

Use nginx or IIS for SSL termination:

# nginx.conf
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_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Multi-Instance Scenarios¶

Scenario 1: Development + Testing¶

# Terminal 1: Development instance
$env:CESIVI__HttpPort = 5000
$env:CESIVI__DataRootPath = "C:\MockData\Dev"
dotnet run --project Cesivi.Server

# Terminal 2: Testing instance
$env:CESIVI__HttpPort = 5100
$env:CESIVI__DataRootPath = "C:\MockData\Test"
dotnet run --project Cesivi.Server

Scenario 2: Multi-Branch Development¶

# Use branch configuration
# Worktree 1 (main)
cd C:\Source\_AI\Cesivi-main
. .\Scripts\Get-BranchConfig.ps1
Set-BranchEnvironment
dotnet run --project Cesivi.Server
# → Runs on port 5000

# Worktree 2 (feature)
cd C:\Source\_AI\Cesivi-feature
. .\Scripts\Get-BranchConfig.ps1
Set-BranchEnvironment
dotnet run --project Cesivi.Server
# → Runs on port 5020

Scenario 3: Docker Multi-Environment¶

# docker-compose.yml
version: '3.8'

services:
  spmock-dev:
    image: Cesivi:latest
    ports:
      - "8080:8080"
    environment:
      - ASPNETCORE_ENVIRONMENT=Development
    volumes:
      - ./MockData-dev:/app/MockData

  spmock-staging:
    image: Cesivi:latest
    ports:
      - "8081:8080"
    environment:
      - ASPNETCORE_ENVIRONMENT=Staging
    volumes:
      - ./MockData-staging:/app/MockData

Configuration Priority¶

ASP.NET Core applies configuration in this order (later overrides earlier):

appsettings.json (lowest priority)
appsettings.{Environment}.json (e.g., appsettings.Production.json)
Environment Variables
Command-line Arguments (highest priority)

Example¶

// appsettings.json
{
  "Cesivi": {
    "HttpPort": 5000  // Priority 1
  }
}

// appsettings.Production.json
{
  "Cesivi": {
    "HttpPort": 8080  // Priority 2 (overrides appsettings.json)
  }
}

# Environment variable
export CESIVI__HttpPort=9000  # Priority 3 (overrides both files)

# Command-line
dotnet run --Cesivi:HttpPort=7000  # Priority 4 (WINS - overrides everything)

Result: Server uses port 7000.

Custom Configuration Files¶

Cesivi Server supports loading configuration from a custom-named config file specified at startup. This provides flexible override behavior for both appsettings.json and environment variables.

Basic Usage¶

# Load custom config (overrides appsettings.json, env vars override custom)
dotnet run --config production.json

# Short form
dotnet run -c production.json

# Load custom config with environment variables taking precedence
dotnet run --config production.json --config-priority env-first

# Load custom config with highest priority (overrides everything including env vars)
dotnet run --config production.json --config-priority force-config

Priority Modes¶

Mode	Priority Order (Lowest → Highest)	Use Case
`default`	appsettings → custom → env vars → CLI	Normal deployment
`env-first`	appsettings → env vars → custom → CLI	Docker with fallbacks
`force-config`	appsettings → env vars → CLI → custom	Locked-down production

Per-Setting Source Control¶

Each setting in your custom config file can specify its own source priority using the _source suffix:

{
  "Cesivi": {
    "HostName": "sharepoint.company.com",
    "HostName_source": "force-config",

    "HttpPort": 8080,
    "HttpPort_source": "default",

    "DataRootPath": "/data",
    "DataRootPath_source": "env-first"
  }
}

Source Values:

Value	Behavior
`default`	Normal priority chain (custom wins over appsettings, env vars win over custom)
`env-first`	Environment variable wins if set, otherwise use config
`force-config`	Config file always wins, even over env vars

Example Config Files¶

Production (production.json) - Lock all settings:

{
  "Cesivi": {
    "HostName": "sharepoint.company.com",
    "HostName_source": "force-config",
    "HttpPort": 80,
    "HttpPort_source": "force-config",
    "HttpsPort": 443,
    "HttpsPort_source": "force-config",
    "UseHttps": true,
    "UseHttps_source": "force-config",
    "DataRootPath": "/var/cesivi/data",
    "DataRootPath_source": "force-config",
    "StorageProvider": "Sqlite",
    "SqlitePath": "/var/cesivi/data/sharepoint.db"
  }
}

Docker Override (docker-override.json) - Let env vars win:

{
  "Cesivi": {
    "HttpPort": 5000,
    "HttpPort_source": "env-first",
    "HttpsPort": 5001,
    "HttpsPort_source": "env-first",
    "DataRootPath": "/data",
    "DataRootPath_source": "env-first",
    "StorageProvider": "FileSystem"
  }
}

Test Scenario (test-scenario.json) - Mixed sources:

{
  "Cesivi": {
    "HostName": "test.local",
    "HostName_source": "force-config",
    "HttpPort": 9999,
    "HttpPort_source": "default",
    "StorageProvider": "InMemory",
    "StorageProvider_source": "force-config"
  }
}

Docker with Custom Config¶

Dockerfile:

COPY my-config.json /app/config.json
CMD ["dotnet", "Cesivi.Server.dll", "--config", "/app/config.json"]

Docker Compose:

services:
  cesivi:
    image: Cesivi:latest
    volumes:
      - ./production.json:/app/config.json:ro
    command: ["--config", "/app/config.json", "--config-priority", "force-config"]

Runtime Mount:

docker run -v ./production.json:/app/config.json cesivi --config /app/config.json

Relative vs Absolute Paths¶

# Relative path (relative to current directory)
dotnet run --config ./configs/my-settings.json

# Absolute path (Windows)
dotnet run --config C:\configs\production.json

# Absolute path (Linux/Docker)
dotnet run --config /etc/cesivi/config.json

Test Environment Configuration¶

.env File (Test Scripts)¶

File: test-scripts/.env (not committed)

# Server Ports
CESIVI_HTTP_PORT=5010
CESIVI_HTTPS_PORT=5011

# MockData Path
CESIVI_DATA_PATH=C:\MockData\WorkTree1

# PnP Module Path
PNP_MODULE_PATH=C:\Source\_AI\Cesivi\SharePointPnPPowerShell2019\3.29.2101.0\SharePointPnPPowerShell2019.psd1

# Test Configuration
TEST_TIMEOUT_SECONDS=120
SERVER_STARTUP_WAIT_SECONDS=15
SERVER_BASE_URL=http://localhost:5010

# Test Credentials
TEST_USERNAME=admin
TEST_PASSWORD=password

Template: test-scripts/.env.template (committed)

Using .env in Tests¶

# Load environment
. "$PSScriptRoot\Load-TestEnv.ps1"

# Use variables
$serverUrl = $env:SERVER_BASE_URL
$port = $env:CESIVI_HTTP_PORT

# Start server with env vars
$env:CESIVI__HttpPort = $env:CESIVI_HTTP_PORT
$env:CESIVI__DataRootPath = $env:CESIVI_DATA_PATH
dotnet run --project Cesivi.Server

Verification¶

Check Current Configuration¶

# Health endpoint includes configuration info
curl http://localhost:5000/_vti_bin/health

# Response includes:
{
  "status": "Healthy",
  "mockDataPath": "C:\\Data\\Cesivi",
  "serverVersion": "1.0.0",
  ...
}

PowerShell Verification¶

# Get configuration from server
$health = Invoke-RestMethod -Uri "http://localhost:5000/_vti_bin/health"
Write-Host "MockData Path: $($health.mockDataPath)"
Write-Host "Environment: $($health.environment)"
Write-Host "Server Version: $($health.serverVersion)"

Best Practices¶

1. Environment Variables for Deployment¶

✅ DO: Use environment variables for Docker, CI/CD, multi-instance ❌ DON'T: Hardcode paths in appsettings.json for deployment

2. Absolute Paths in Production¶

✅ DO: Use absolute paths like /var/lib/Cesivi/data ⚠️ CAUTION: Relative paths depend on working directory

3. Separate Data Per Environment¶

✅ DO: Use different MockData paths for dev/test/staging/prod ❌ DON'T: Share MockData between incompatible environments

4. Version Control¶

✅ DO: Commit .env.template, .branch-config.json ✅ DO: Add .env, launchSettings.json to .gitignore ❌ DON'T: Commit secrets or absolute paths

5. Logging in Production¶

✅ DO: Set log level to Warning or Error ✅ DO: Configure log rotation/cleanup ❌ DON'T: Use Debug/Trace logging (performance impact)

Troubleshooting¶

Configuration Not Applied¶

Check priority:

# Environment variable overrides appsettings.json
$env:CESIVI__HttpPort = 9000
dotnet run
# Server uses port 9000 (not from appsettings.json)

Environment Variable Name Issues¶

Correct syntax: - CESIVI__DataRootPath (double underscore!) - Logging__LogLevel__Default

Incorrect: - CESIVI_DataRootPath (single underscore - won't work) - Cesivi:DataRootPath (colon - only for command-line)

Path with Spaces¶

# Use quotes
$env:CESIVI__DataRootPath = "C:\Mock Data\Test"

# JSON: escape backslashes
"DataRootPath": "C:\\Mock Data\\Test"

Next Steps¶

Start server → Quick Start Guide
Deploy to production → Docker Deployment Guide
Learn features → Features Overview
Troubleshoot issues → Troubleshooting Guide

← Back to Setup | View All Docs