Skip to content

Docker Deployment Troubleshooting Guide

Home → Documentation → Troubleshooting → Docker

Version: 1.0 Last Updated: 2025-11-05 Applies To: Cesivi Server (Docker Deployment)

Table of Contents

  1. Common Issues
  2. Image Build Failures
  3. Container Startup Failures
  4. Network Connectivity
  5. Volume & Persistence Issues
  6. Performance Problems
  7. Health Check Failures
  8. Diagnostic Commands
  9. Configuration Issues
  10. Known Limitations
  11. FAQ

Common Issues

Image Build Failures

Error: "Unable to locate package curl"

Symptoms: 

#9 1.234 E: Unable to locate package curl
executor failed running [/bin/sh -c apt-get update && apt-get install -y curl]: exit code 100

Solutions: 1. Check if base image has changed - update Dockerfile base image version 2. Run with --no-cache to force fresh package index: 

docker build --no-cache -t Cesivi:latest .
3. Verify internet connectivity during build 4. Try alternative package installation: 
RUN apt-get update && apt-get install -y --no-install-recommends curl

Error: "dotnet restore" fails with authentication error

Symptoms: 

#12 23.456 error NU1301: Unable to load the service index for source https://api.nuget.org/v3/index.json
#12 23.457 error NU1301: Response status code does not indicate success: 401 (Unauthorized)

Solutions: 1. Corporate proxy/firewall: Add proxy environment variables to Dockerfile: 

ENV HTTP_PROXY=http://proxy.company.com:8080
ENV HTTPS_PROXY=http://proxy.company.com:8080
2. Private NuGet feed authentication: Use build arguments for credentials 3. Network issue: Check Docker daemon network settings (/etc/docker/daemon.json) 4. NuGet cache corruption: Clear NuGet cache: 
docker build --no-cache .

Error: Build fails with "COPY failed: no source files were specified"

Symptoms: 

#14 ERROR [build 4/10] COPY ["Cesivi.Server/Cesivi.csproj", "Cesivi.Server/"]
------
 > [build 4/10] COPY ["Cesivi.Server/Cesivi.csproj", "Cesivi.Server/"]:
------
failed to compute cache key: "/Cesivi.Server/Cesivi.csproj" not found

Solutions: 1. Incorrect build context: Ensure building from repository root: 

# CORRECT - from repository root
docker build -t Cesivi:latest .

# WRONG - from subdirectory
cd Cesivi.Server && docker build .
2. .dockerignore too aggressive: Check if .dockerignore excludes necessary files 3. Case sensitivity (Linux hosts): Verify exact file name casing

Error: "The runtime pack for Microsoft.NETCore.App was not downloaded"

Symptoms: 

#18 120.234 error NU1102: Unable to find package Microsoft.NETCore.App.Runtime.linux-x64 with version (>= 9.0.0)

Solutions: 1. Base image version mismatch: Update Dockerfile to use correct .NET SDK version: 

FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS runtime
2. Corrupted image: Pull fresh base images: 
docker pull mcr.microsoft.com/dotnet/sdk:10.0
docker pull mcr.microsoft.com/dotnet/aspnet:10.0
3. Architecture mismatch: Specify platform explicitly: 
docker build --platform linux/amd64 -t Cesivi:latest .

Container Startup Failures

Error: Container starts but immediately exits

Symptoms: 

$ docker ps -a
CONTAINER ID   IMAGE              STATUS
abc123def456   Cesivi     Exited (139) 2 seconds ago

Diagnostic Steps: 

# 1. Check container logs
docker logs cesivi-server

# 2. Check exit code meaning
docker inspect cesivi-server --format='{{.State.ExitCode}}'
# Exit code 139 = Segmentation fault (usually .NET runtime issue)
# Exit code 1 = Application error
# Exit code 137 = Killed by OOM killer

# 3. Run container in interactive mode to debug
docker run -it --rm Cesivi:latest /bin/bash

Common Solutions:

Exit Code 1 (Application Error): - Check logs for unhandled exceptions - Verify environment variables (esp. Cesivi__DataRootPath) - Check file permissions on /app/MockData

Exit Code 137 (Out of Memory): - Increase memory limit in docker-compose.yml: 

deploy:
  resources:
    limits:
      memory: 2G  # Increase from 1G

Exit Code 139 (Segmentation Fault): - Usually indicates .NET runtime corruption - Rebuild image with --no-cache - Try different base image tag (e.g., 9.0-alpine vs 9.0)

Error: "bind: address already in use"

Symptoms: 

Error starting userland proxy: listen tcp4 0.0.0.0:5020: bind: address already in use

Solutions: 1. Find conflicting process: 

# Linux/macOS
sudo lsof -i :5020
sudo netstat -tulpn | grep :5020

# Windows
netstat -ano | findstr :5020
tasklist /FI "PID eq <PID>"

  1. Stop conflicting container: 

    docker ps | grep 5020
docker stop <container-id>

  2. Change port in docker-compose.yml: 

    ports:
  - "5030:5020"  # Map external 5030 to internal 5020

  3. Stop all Cesivi containers: 

    docker ps -a | grep cesivi | awk '{print $1}' | xargs docker rm -f

Error: "permission denied" errors in logs

Symptoms: 

[ERROR] Failed to write to /app/MockData/Logs/server.log: Permission denied
[ERROR] Cannot create directory /app/MockData/Sites: Permission denied

Solutions: 1. Volume permission mismatch: Fix host directory permissions: 

# Linux/macOS - give write permission
chmod -R 777 ./MockData

# Better: Match container user UID (sharepoint user = UID 999)
sudo chown -R 999:999 ./MockData

  1. SELinux issue (RHEL/CentOS): 

    # Option 1: Add :z suffix to volume mount (docker-compose.yml)
volumes:
  - ./MockData:/app/MockData:z

# Option 2: Disable SELinux enforcement for container
chcon -Rt svirt_sandbox_file_t ./MockData

  2. Run as root (NOT RECOMMENDED for production): 

    # Comment out in Dockerfile:
# USER sharepoint

Network Connectivity

Error: Cannot connect to mock server from host

Symptoms: 

PS> Connect-PnPOnline -Url http://localhost:5020
Connect-PnPOnline: Connection failed

Diagnostic Steps: 

# 1. Check container is running
docker ps | grep cesivi

# 2. Check port mapping
docker port cesivi-server
# Expected: 5020/tcp -> 0.0.0.0:5020

# 3. Test from host
curl http://localhost:5020
curl http://127.0.0.1:5020

# 4. Test from inside container
docker exec -it cesivi-server curl http://localhost:8080

Solutions:

Port mapping issue: 

# Ensure docker-compose.yml has correct port mapping
ports:
  - "5020:8080"  # Host:Container

# Verify ASPNETCORE_URLS matches container port
environment:
  - ASPNETCORE_URLS=http://+:8080

Firewall blocking: 

# Linux - allow port
sudo ufw allow 5020/tcp
sudo firewall-cmd --add-port=5020/tcp --permanent

# Windows - add firewall rule
netsh advfirewall firewall add rule name="Cesivi" dir=in action=allow protocol=TCP localport=5020

Docker network mode issue: 

# If using host network mode, ports should NOT be mapped
network_mode: host  # Remove port mappings if using this

Error: Container cannot access external URLs (e.g., plugin endpoints)

Symptoms: 

[ERROR] Plugin request to http://host.docker.internal:5001 timed out
[ERROR] Unable to connect to http://192.168.1.100:5001

Solutions:

Access host from container (Windows/macOS): 

{
  "EndpointUrl": "http://host.docker.internal:5001"
}

Access host from container (Linux): 

# Add extra_hosts to docker-compose.yml
services:
  cesivi:
    extra_hosts:
      - "host.docker.internal:host-gateway"

Access specific IP: 

# Ensure container has correct DNS
docker exec cesivi-server cat /etc/resolv.conf

# Test connectivity
docker exec cesivi-server ping 192.168.1.100
docker exec cesivi-server curl http://192.168.1.100:5001

Corporate proxy: 

# Add proxy environment variables
environment:
  - HTTP_PROXY=http://proxy.company.com:8080
  - HTTPS_PROXY=http://proxy.company.com:8080
  - NO_PROXY=localhost,127.0.0.1

Volume & Persistence Issues

Error: MockData lost after container restart

Symptoms: - Site collections created in container disappear after restart - Empty MockData directory after docker-compose down

Solutions:

Named volume not persisting (docker-compose.yml): 

# WRONG - creates anonymous volume
volumes:
  - /app/MockData

# CORRECT - maps to host directory
volumes:
  - ./MockData:/app/MockData

# CORRECT - uses named volume
volumes:
  - mock-data:/app/MockData

volumes:
  mock-data:

Volume deleted by docker-compose down -v: 

# DON'T use -v flag if you want to keep data
docker-compose down     # Keeps volumes
docker-compose down -v  # DELETES volumes

Verify volume persistence: 

# Check volume exists
docker volume ls | grep mock

# Inspect volume location
docker volume inspect cesivi_mock-data

# Backup volume
docker run --rm -v cesivi_mock-data:/data -v $(pwd):/backup alpine tar czf /backup/mockdata-backup.tar.gz /data

Error: "Disk full" errors

Symptoms: 

[ERROR] System.IO.IOException: There is not enough space on the disk
[ERROR] Failed to save file to /app/MockData/Sites/...

Solutions:

Check disk usage: 

# Host disk space
df -h

# Docker disk usage
docker system df

# Container disk usage
docker exec cesivi-server df -h

Clean up Docker resources: 

# Remove unused images
docker image prune -a

# Remove unused volumes
docker volume prune

# Remove everything unused (CAREFUL!)
docker system prune -a --volumes

Increase Docker Desktop disk size (Windows/macOS): - Docker Desktop Settings → Resources → Disk image size

Move Docker data directory (Linux): 

// /etc/docker/daemon.json
{
  "data-root": "/mnt/newlocation/docker"
}

Performance Problems

Issue: Slow container startup (>30 seconds)

Diagnostic Steps: 

# Time container startup
time docker-compose up -d

# Check startup logs
docker-compose logs -f | grep -E "Started|Listening"

Solutions:

MockData directory too large: 

# Check MockData size
du -sh ./MockData

# Solution: Clean up old data or use fresh volume
docker-compose down
mv MockData MockData.backup
mkdir MockData
docker-compose up -d

Health check too aggressive: 

healthcheck:
  start_period: 40s  # Increase from 10s
  interval: 60s      # Reduce frequency
  timeout: 10s

Resource limits too low: 

deploy:
  resources:
    limits:
      cpus: '4'      # Increase CPU
      memory: 2G     # Increase memory

Issue: High CPU usage (>80% sustained)

Diagnostic Steps: 

# Monitor container resources
docker stats cesivi-server

# Check process list
docker exec cesivi-server ps aux

# Analyze logs for errors
docker logs cesivi-server | grep -E "ERROR|Exception"

Solutions:

Infinite loop in plugin: - Check plugin endpoints are responding correctly - Disable plugins to isolate issue: 

docker exec cesivi-server cat /app/appsettings.Plugins.json

Logging too verbose: 

environment:
  - Logging__LogLevel__Default=Warning  # Reduce from Information
  - Logging__LogLevel__Microsoft.AspNetCore=Error

Large site collection: - Reduce MockData size - Optimize queries to avoid loading entire collections

Issue: High memory usage (approaching limit)

Diagnostic Steps: 

# Check memory usage
docker stats cesivi-server --no-stream

# Inspect memory limit
docker inspect cesivi-server | grep -i memory

Solutions:

Increase memory limit: 

deploy:
  resources:
    limits:
      memory: 2G  # Increase from 1G

Enable .NET garbage collection optimization: 

environment:
  - DOTNET_gcServer=1               # Server GC (better for multi-core)
  - DOTNET_GCConserveMemory=5       # Aggressive memory conservation (1-9)

Restart container periodically (workaround): 

# Add to cron (restart daily at 2 AM)
0 2 * * * docker restart cesivi-server

Health Check Failures

Error: Container marked as "unhealthy"

Symptoms: 

$ docker ps
CONTAINER ID   STATUS
abc123def456   Up 2 minutes (unhealthy)

Diagnostic Steps: 

# Check health check logs
docker inspect cesivi-server --format='{{json .State.Health}}' | jq

# Manual health check test
docker exec cesivi-server curl -f http://localhost:8080/

# Check if application is listening
docker exec cesivi-server netstat -tulpn | grep 8080

Solutions:

Port mismatch in health check: 

# Ensure health check URL matches ASPNETCORE_URLS
environment:
  - ASPNETCORE_URLS=http://+:8080

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:8080/"]  # Must match port

Application not responding: 

# Check application logs
docker logs cesivi-server | tail -n 50

# Check if .NET process running
docker exec cesivi-server ps aux | grep dotnet

Curl not installed (if using minimal base image): 

# Ensure curl installed in Dockerfile
RUN apt-get update && apt-get install -y curl

Increase timeout: 

healthcheck:
  timeout: 10s        # Increase from 3s
  start_period: 60s   # Increase from 10s
  interval: 60s

Diagnostic Commands

Essential Docker Commands

# View all containers (including stopped)
docker ps -a

# View container logs (live tail)
docker-compose logs -f cesivi

# View last 100 log lines
docker logs --tail 100 cesivi-server

# Inspect container configuration
docker inspect cesivi-server

# Execute command in running container
docker exec -it cesivi-server /bin/bash

# Check resource usage
docker stats cesivi-server

# Check container networking
docker network inspect sharepoint-network

# View container processes
docker top cesivi-server

# View port mappings
docker port cesivi-server

Application-Specific Commands

# Check .NET version
docker exec cesivi-server dotnet --version

# List files in MockData
docker exec cesivi-server ls -la /app/MockData

# Check application configuration
docker exec cesivi-server cat /app/appsettings.json

# Test endpoint from inside container
docker exec cesivi-server curl http://localhost:8080/_vti_bin/diagnostics

# Check environment variables
docker exec cesivi-server env | grep Cesivi

Troubleshooting Workflow

# Step 1: Verify container running
docker ps | grep cesivi

# Step 2: Check logs for errors
docker logs cesivi-server | grep -E "ERROR|Exception|Failed"

# Step 3: Verify health check
docker inspect cesivi-server --format='{{.State.Health.Status}}'

# Step 4: Test connectivity from inside container
docker exec cesivi-server curl http://localhost:8080/

# Step 5: Test connectivity from host
curl http://localhost:5020/

# Step 6: Check resource usage
docker stats --no-stream cesivi-server

# Step 7: Inspect full configuration
docker inspect cesivi-server > container-inspect.json

Configuration Issues

Issue: Environment variables not applied

Symptoms: - Container ignores Cesivi__DataRootPath setting - Logs show default values instead of configured values

Solutions:

Check environment variable syntax: 

# CORRECT - double underscore for nested config
environment:
  - Cesivi__DataRootPath=/app/MockData
  - Cesivi__HttpPort=5020

# WRONG - single underscore
environment:
  - Cesivi_DataRootPath=/app/MockData

Verify variables are set: 

docker exec cesivi-server env | grep Cesivi

Check appsettings.json priority: 

# Environment variables override appsettings.json
# Verify appsettings.json doesn't have conflicting values
docker exec cesivi-server cat /app/appsettings.json

Issue: Hostname resolution not working

Symptoms: 

Cannot resolve hostname 'mocksharepoint.local'

Solutions:

Add to hosts file (development): 

# Linux/macOS: /etc/hosts
# Windows: C:\Windows\System32\drivers\etc\hosts
127.0.0.1 mocksharepoint.local

Use container name in Docker network: 

# From another container in same network
curl http://cesivi:5020/

Configure DNS in docker-compose.yml: 

services:
  cesivi:
    hostname: mocksharepoint.local
    extra_hosts:
      - "mocksharepoint.local:127.0.0.1"

Known Limitations

Docker-Specific Limitations

  1. Windows Containers Not Supported
  2. Cesivi only supports Linux containers

  3. Windows Server Core containers are not tested

  4. HTTPS Certificate Limitations

  5. Self-signed certificates may require additional configuration
  6. Browser trust issues with self-signed certs

  7. Solution: Use reverse proxy (nginx) with proper certificates

  8. File System Performance

  9. Bind mounts on Windows/macOS may have slower file I/O

  10. Solution: Use named volumes for better performance

  11. Inter-Container Communication

  12. Plugins running on host need host.docker.internal (not available on Linux by default)
  13. Solution: Use --add-host or run plugins in containers

Application Limitations in Docker

  1. Active Directory Integration
  2. AD integration not supported in containerized environment

  3. All authentication is mock/bypass mode

  4. SharePoint Timer Jobs

  5. No equivalent for SharePoint timer jobs

  6. Background tasks must be implemented as separate containers

  7. Large File Uploads

  8. Limited by container memory settings
  9. Increase memory limit for large files (>100MB)

FAQ

General Questions

Q: What is the recommended memory limit? A: Minimum 512MB, recommended 1GB for typical usage, 2GB+ for large sites or heavy load.

Q: Can I run multiple Cesivi containers? A: Yes, but ensure different port mappings and separate MockData volumes. 

# Container 1
ports:
  - "5020:8080"
volumes:
  - ./MockData1:/app/MockData

# Container 2
ports:
  - "5030:8080"
volumes:
  - ./MockData2:/app/MockData

Q: How do I backup my MockData? A: Copy the host directory or use Docker volume backup: 

docker run --rm -v cesivi_mock-data:/data -v $(pwd):/backup alpine tar czf /backup/backup.tar.gz /data

Performance Questions

Q: Why is the container slow on Windows/macOS? A: Bind mounts have slower I/O on Windows/macOS. Use named volumes: 

volumes:
  - mock-data:/app/MockData  # Named volume (faster)
  # - ./MockData:/app/MockData  # Bind mount (slower on Win/Mac)

Q: How can I improve startup time? A: 1. Reduce MockData size 2. Increase start_period in health check 3. Use smaller base image (aspnet:10.0-alpine) 4. Pre-warm with docker-compose up before first use

Networking Questions

Q: How do I access the container from another machine? A: Bind to 0.0.0.0 (default) and ensure firewall allows the port: 

ports:
  - "5020:8080"  # Accessible from network

# NOT this:
ports:
  - "127.0.0.1:5020:8080"  # Only accessible from localhost

Q: Can I use HTTPS? A: Yes, configure ASPNETCORE_URLS and provide certificate: 

environment:
  - ASPNETCORE_URLS=https://+:5021
  - ASPNETCORE_Kestrel__Certificates__Default__Path=/app/certs/cert.pfx
  - ASPNETCORE_Kestrel__Certificates__Default__Password=YourPassword
volumes:
  - ./certs:/app/certs:ro

Data Persistence Questions

Q: Where is my data stored? A: Depends on volume configuration: 

# Named volume - stored in Docker volume directory
docker volume inspect cesivi_mock-data

# Bind mount - stored in host directory
./MockData/

Q: How do I reset MockData to empty state? A: 

docker-compose down
rm -rf ./MockData/*  # Or delete named volume
docker-compose up -d

Getting Help

Before Reporting Issues

  1. Check this troubleshooting guide
  2. Review Docker logs: docker logs cesivi-server
  3. Verify configuration: docker inspect cesivi-server
  4. Test with minimal docker-compose.yml (no custom config)
  5. Check GitHub Issues for similar problems

When Reporting Issues

Include: - Docker version: docker --version - Docker Compose version: docker-compose --version - OS and version - Complete docker-compose.yml (remove sensitive data) - Container logs: docker logs cesivi-server - Container inspect output: docker inspect cesivi-server - Steps to reproduce

Useful Resources

Document Version: 1.0 Document ID: S1.134 Work Stream: Documentation Completion (Option A)