Platform: Docker Linux

Reproduce bugs on Linux using Docker. Use when the host is macOS/Windows, or to test older SkiaSharp versions that lack host-platform native assets.

Contents

1. Signals — Prerequisites — Quick Repro Pattern
2. Required Dependencies — Platform Variants
3. Run & Verify — Recording in JSON
4. Common Issues — Conclusion Mapping
5. Main Source Testing (Phase 3C)

See also: the issue-fix skill's docker-testing.md for full dependency matrix and troubleshooting.

Signals

Linux, Docker, container, NativeAssets.Linux, fontconfig, "works on Windows/Mac but not Linux", DllNotFoundException on Linux, case-sensitivity issues, server deployment, Azure App Service, AWS Lambda.

Also use for:

• Old versions (1.68.x) on Apple Silicon — no arm64 native exists, must use --platform linux/amd64
• Cross-platform verification — Docker Linux is the default alternative platform
• Inconclusive host results — second environment may clarify

Prerequisites

• Docker Desktop: docker --version
• For old SkiaSharp (pre-2.x): use --platform linux/amd64 (Rosetta emulation on Apple Silicon)

Quick Repro Pattern

docker run --rm --platform linux/amd64 mcr.microsoft.com/dotnet/sdk:8.0 bash -c '
apt-get update -qq && apt-get install -y -qq libfontconfig1 2>&1 | tail -1
mkdir -p /tmp/skiasharp/repro/{timestamp} && cd /tmp/skiasharp/repro/{timestamp}
dotnet new console -n Repro --framework {reporter_tfm} --no-restore 2>&1 | tail -1
cd Repro
dotnet add package SkiaSharp --version {reporter_version} --no-restore 2>&1 | tail -1
dotnet add package SkiaSharp.NativeAssets.Linux --version {reporter_version} --no-restore 2>&1 | tail -1
cat > Program.cs << "ENDOFFILE"
{reporter_code}
ENDOFFILE
dotnet restore 2>&1 | tail -1
dotnet run 2>&1
'

Adapt the SDK image tag to match {reporter_tfm}:

• net6.0 → sdk:6.0
• net8.0 → sdk:8.0
• net9.0 → sdk:9.0
• net10.0 → sdk:10.0

Required Dependencies

⚠️ libfontconfig1 is MANDATORY — without it you get DllNotFoundException for libSkiaSharp.

# Debian/Ubuntu (default SDK images)
apt-get update -qq && apt-get install -y -qq libfontconfig1

# Alpine (sdk:8.0-alpine) — use sh not bash
apk add --no-cache fontconfig

For rendering/font bugs, also install fonts:

apt-get install -y -qq fonts-dejavu-core   # Debian
apk add --no-cache ttf-dejavu              # Alpine

Platform Variants

Run & Verify

All output comes through Docker stdout/stderr. Capture the full output of the docker run command.

• Exit code 0 + expected output → success
• Non-zero exit code or crash → failure
• Exit code 0 but wrong values → step result wrong-output, conclusion reproduced

Recording in JSON

{
  "environment": {
    "os": "Linux (Docker)",
    "arch": "x64",
    "dotnetVersion": "8.0.xxx",
    "skiaSharpVersion": "{reporter_version}",
    "dockerUsed": true
  }
}

Tag versionResults entries with "platform": "docker-linux-x64" (or docker-linux-arm64).

Common Issues

Conclusion Mapping

Main Source Testing (Phase 3C)

For Docker/Linux bugs, Phase 3C tests the main branch console sample inside Docker:

# Return to the SkiaSharp repo root — ensure native binaries exist
cd "$(git rev-parse --show-toplevel)"
[ -d "output/native" ] && ls output/native/ | head -5 || dotnet cake --target=externals-download

# Build the console sample from source
dotnet build samples/Basic/Console/SkiaSharpSample/SkiaSharpSample.csproj

# Run in Docker with the source-built binary
dotnet publish samples/Basic/Console/SkiaSharpSample/SkiaSharpSample.csproj -r linux-x64 --no-self-contained -o /tmp/skiasharp/repro/{timestamp}/publish/
docker run --rm --platform linux/amd64 -v /tmp/skiasharp/repro/{timestamp}/publish:/app mcr.microsoft.com/dotnet/runtime:8.0 bash -c '
apt-get update -qq && apt-get install -y -qq libfontconfig1 2>&1 | tail -1
cd /app && dotnet SkiaSharpSample.dll 2>&1
'

Alternatively, if the sample doesn't cover the specific bug, temporarily modify samples/Basic/Console/SkiaSharpSample/Program.cs with the repro code, rebuild, and run in Docker. Revert with git checkout after recording the result.