Cesivi Server Tutorials¶
Welcome to the Cesivi Server tutorials! These step-by-step guides will help you set up and configure Cesivi Server for various scenarios.
Quick Reference: Choose Your Tutorial¶
| Tutorial | Auth | Storage | Search | Platform | Time | Best For |
|---|---|---|---|---|---|---|
| A | OAuth2/OIDC | SQLite | TfIdf | Windows | ~15 min | Enterprise dev with SSO |
| B | NTLM+LDAP | LiteDB | TfIdf | Docker | ~20 min | AD simulation in containers |
| C | NTLM | FileSystem | TfIdf | Windows | ~10 min | Legacy app testing |
| D | Accept All | In-Memory | Lucene | Windows | ~10 min | Full-text search dev |
| E | Accept All | In-Memory | TfIdf | Docker | ~5 min | CI/CD pipelines |
| F | OAuth2 | PostgreSQL | Lucene | Kubernetes | ~45 min | Production deployment |
Tutorials by Scenario¶
Development & Testing¶
Tutorial A: OAuth2/OIDC + SQLite on Windows¶
Best for: Enterprise development with Single Sign-On requirements
Set up Cesivi with modern OAuth2/OIDC authentication using dev-oidc, SQLite for persistent storage, and TfIdf search. Perfect for: - Testing applications that use Azure AD, Okta, or other OIDC providers - Development requiring persistent data across restarts - Teams needing reproducible authentication flows
Components: dev-oidc + SQLite + TfIdf + Windows
Tutorial B: LDAP + LiteDB on Docker¶
Best for: Simulating Active Directory environments in containers
Deploy Cesivi with NTLM authentication backed by OpenLDAP, using LiteDB for document storage. Ideal for: - Testing applications that rely on Active Directory - Containerized development environments - Teams without access to real AD infrastructure
Components: OpenLDAP + LiteDB + TfIdf + Docker Compose
Tutorial C: NTLM + FileSystem on Windows¶
Best for: Testing legacy applications with Windows authentication
Configure Cesivi with NTLM authentication using configuration-based users (no AD required) and FileSystem storage. Great for: - Testing desktop applications using NetworkCredential - Migration testing from on-premises SharePoint - CSOM and PnP PowerShell development
Components: NTLM (config-based) + FileSystem + TfIdf + Windows
Tutorial D: Accept All + Lucene on Windows¶
Best for: Search functionality development and testing
Set up Cesivi with no authentication overhead and Lucene full-text search. Perfect for: - Testing search-heavy applications - Performance benchmarking - Rapid prototyping without auth complexity
Components: Accept All + In-Memory + Lucene + Windows
Tutorial E: Accept All + TfIdf on Docker¶
Best for: CI/CD pipelines and automated testing
Deploy Cesivi in Docker with zero authentication and lightweight search. Ideal for: - GitHub Actions / GitLab CI integration - Automated integration tests - Quick-start containerized development
Components: Accept All + In-Memory + TfIdf + Docker
Production Deployment¶
Tutorial F: Production-Ready Setup¶
Best for: QA environments, staging, and team development infrastructure
Deploy a production-grade Cesivi Server on Kubernetes with: - High availability (3+ replicas) - OAuth2/OIDC with Azure AD - PostgreSQL for persistent storage - Lucene for full-text search - HTTPS, monitoring, and alerts
Components: OAuth2 + PostgreSQL + Lucene + Kubernetes
Component Comparison¶
Authentication Providers¶
| Provider | Security | Setup Complexity | Best Use Case |
|---|---|---|---|
| Accept All | None | Trivial | Testing, CI/CD |
| NTLM (Config) | Medium | Low | Local development |
| NTLM (LDAP) | Medium | Medium | AD simulation |
| OAuth2/OIDC | High | Medium | Enterprise, Production |
Storage Providers¶
| Provider | Persistence | Performance | Scalability | Best Use Case |
|---|---|---|---|---|
| In-Memory | None | Excellent | Single node | Testing, benchmarks |
| FileSystem | Disk | Good | Single node | Development |
| SQLite | Disk | Good | Single node | Persistent dev |
| LiteDB | Disk | Good | Single node | Document-heavy apps |
| PostgreSQL | Disk | Excellent | Multi-node | Production |
Search Engines¶
| Engine | Features | Memory | Setup | Best Use Case |
|---|---|---|---|---|
| TfIdf | Basic keyword | Low | None | Simple search |
| Lucene | Full-text, fuzzy, wildcard | Medium | Index dir | Advanced search |
Prerequisites by Platform¶
Windows¶
- .NET 10.0 SDK
- PowerShell 5.1+
- (Optional) Docker Desktop for Windows
Docker / Linux¶
- Docker Desktop or Docker Engine
- Docker Compose
- (Optional) kubectl for Kubernetes tutorials
Kubernetes (Tutorial F)¶
- kubectl configured
- Kubernetes cluster (Docker Desktop K8s, minikube, or cloud)
- OIDC provider (Azure AD, Keycloak, etc.)
Quick Start Commands¶
Fastest Setup (Tutorial E)¶
docker run -d -p 8080:8080 \
-e Cesivi__StorageProvider=InMemory \
-e Cesivi__SearchEngine=TfIdf \
-e Cesivi__Authentication__AcceptAllCredentials=true \
ghcr.io/your-org/cesivi:latest
Windows Development (Tutorial D)¶
cd Cesivi.Server
$env:ASPNETCORE_ENVIRONMENT = "Development"
dotnet run
Test Connectivity¶
curl http://localhost:5000/_api/web -H "Accept: application/json;odata=verbose"
Troubleshooting¶
Common Issues¶
Port already in use:
# Find process using port
netstat -ano | findstr :5000 # Windows
lsof -i :5000 # Linux/Mac
Docker container won't start:
docker logs <container-name>
docker inspect <container-name> | jq '.[0].State'
Authentication failures: - Check credentials match configuration exactly - Verify domain format (DOMAIN\user vs user@domain.com) - Check server logs for NTLM/OAuth negotiation details
Additional Resources¶
- Identity Providers Guide - Deep dive into authentication options
- OAuth2 Setup Guide - Detailed OIDC configuration
- NTLM Setup Guide - Windows authentication details
- API Reference - Complete REST/SOAP API documentation
- Deployment Guide - Production deployment strategies
- Troubleshooting Guide - Common issues and solutions
Contributing¶
Found an issue or have a suggestion for these tutorials? Please: 1. Check existing GitHub Issues 2. Open a new issue with the "tutorial" label 3. Include your platform, tutorial name, and specific steps where you encountered problems
Last updated: December 2025