Knowledge Hub

Compatibility Testing Matrix

Purpose

CleanStart images are built on GLIBC and the APK package ecosystem. This matrix defines which application frameworks are officially tested (Tier 1), which are community-tested (Tier 2), and which should work but aren't tested (Tier 3). It also documents known incompatibilities and their workarounds.

Use this matrix to verify your app framework is supported before you invest effort, understand support levels and response times for your chosen framework, find workarounds for runtimes that aren't fully supported, and understand what "compatible" actually means in practice.

Support Tier System

Tier 1: Officially Tested

These frameworks and runtimes are part of CleanStart's continuous integration pipeline. Every release is tested against these combinations.

What this means for you: Issues in Tier 1 frameworks are bugs and get fixed with SLA coverage. Security patches are prioritized for these frameworks, and comprehensive documentation is available. You can expect a response time of 1-2 business days for issues.

Testing scope: Tier 1 testing verifies that your application starts successfully, that standard operations work (such as web server and database connections), that security properties are verified (no-shell, read-only FS, non-root), and that the upgrade path from previous versions is tested and works.

Tier 2: Community Tested

These frameworks have been validated by customers and community members. Not part of regular CI, but proven to work.

What this means for you: Tier 2 frameworks are generally stable, though edge cases may exist. Issues are accepted but treated with lower priority than Tier 1. You can expect a fix timeline of 2-4 weeks. The community may provide workarounds before an official fix is available.

Testing scope: Tier 2 testing verifies that the application starts and that basic operations work. However, Tier 2 frameworks may not be tested with the latest image version, so compatibility should be verified in your specific use case.

Tier 3: Expected Compatible

These frameworks should work due to GLIBC compatibility, but have no specific testing. Use at your own risk.

What this means for you: Tier 3 frameworks receive no official support. Issues are reported as feature requests rather than bugs. The fix timeline is 4 or more weeks, or sometimes longer. You may need to work around issues yourself rather than waiting for an official fix.

Why Tier 3 is viable: CleanStart images are GLIBC-based, so any GLIBC-compatible application should run. Tier 3 is truly "should work" based on platform compatibility, not because of extensive application testing. If your framework is GLIBC-compatible, it will likely work even without official support.

Language Runtime Matrix

Python

Version	Tier	Test Coverage	Support Ends	Notes
3.12	1	Full	Oct 2027	Current primary version, all packages tested
3.11	1	Full	Oct 2027	LTS, widely used, full support
3.10	2	Community	Oct 2026	Approaching EOL, migration path recommended
3.9	3	None	Oct 2025	EOL, not tested, use 3.10+ if possible
3.8	3	None	Oct 2024	EOL, use 3.10+
2.7	3	None	Jan 2020	EOL, no longer supported anywhere

Python Framework Compatibility:

Framework	Version	Tier	Notes
Flask	3.x	1	Fully tested, async support in 2.x+
FastAPI	0.100+	1	Async tested, Starlette verified
Django	4.2+	1	Full ORM, migrations, async views
Django	3.2	2	LTS version, community tested
Celery	5.x	2	Task queue, async broker tested
SQLAlchemy	2.x	1	ORM fully supported, async engine tested
Pandas	2.x	1	Data manipulation, CSV/Parquet I/O tested
NumPy	1.24+	1	Numerical computing verified
Requests	2.x	1	HTTP library, SSL verified
pydantic	2.x	1	Validation, async validators tested
asyncio	stdlib	1	Built-in, full support
pytest	7.x+	1	Testing framework included

Python Package Manager Compatibility:

Package Manager	Method	Tier	Notes
pip	`pip install`	1	Standard method, lock files supported
poetry	`poetry install`	1	Dependency resolution, lock files
pipenv	`pipenv install`	2	Virtual env management (slower on startup)
uv	`uv pip install`	1	Fast replacement for pip, drop-in compatible
conda	N/A	3	Not supported (adds heavy dependencies)

Python Web Server Deployment:

Server	Version	Tier	Notes
Gunicorn	20.x+	1	Most common, worker types tested
uWSGI	2.x	2	Works but not routinely tested
Hypercorn	0.x	1	ASGI server for async apps
Uvicorn	0.2x+	1	FastAPI default, fully tested

Node.js

Version	Tier	Test Coverage	Support Ends	Notes
20 LTS	1	Full	April 2026	Current LTS, all packages tested
18 LTS	1	Full	April 2025	Previous LTS, still widely used
22	2	Community	Oct 2025	Latest, early adoption only
16 LTS	3	None	Sept 2023	EOL, migrate to 18+
14 LTS	3	None	April 2023	EOL, use 18+

Node.js Framework Compatibility:

Framework	Version	Tier	Notes
Express	4.x	1	Web framework, middleware tested
Fastify	4.x	1	Fast HTTP server, async/await native
Nest.js	10.x	1	Enterprise framework, TypeScript tested
Next.js	14.x	1	React framework, SSR/SSG tested
React	18.x	1	Frontend (in Node SSR contexts)
Vue	3.x	1	Frontend framework
Hapi	21.x	2	Enterprise framework, less common
Koa	2.x	1	Lightweight HTTP framework
Socket.io	4.x	1	Real-time communication
GraphQL-js	16.x+	1	GraphQL implementation
Apollo Server	4.x	1	Apollo GraphQL server
Prisma	5.x	1	ORM, migrations verified
TypeORM	0.3.x	1	ORM for TypeScript
Sequelize	6.x	1	ORM for SQL databases

Node.js Package Manager Compatibility:

Manager	Method	Tier	Notes
npm	`npm install`	1	Standard, lock files default
yarn	`yarn install`	1	Alternative, v3+ with corepack
pnpm	`pnpm install`	1	Faster, monorepo support
Corepack	Built-in	1	Version manager for npm/yarn/pnpm

Node.js Runtime Features:

Feature	Tier	Notes
async/await	1	Native, no transpilation needed
Promises	1	Native
Worker Threads	1	Multi-threading support
Cluster module	1	Process clustering
Stream API	1	Streaming I/O
Buffer API	1	Binary data handling

Go

Version	Tier	Test Coverage	Support Ends	Notes
1.22	1	Full	Feb 2025	Current stable
1.21	1	Full	Aug 2024	Previous stable, still supported
1.20	2	Community	Feb 2024	Older, approaching EOL
1.19	3	None	Dec 2023	EOL

Go Framework Compatibility:

Framework	Version	Tier	Notes
Gin	1.x	1	HTTP web framework, high performance
Echo	4.x	1	Lightweight web framework
Gorilla/mux	-	1	Router, middleware, request handling
gRPC	1.x	1	RPC framework, protocol buffers
GORM	1.x	1	ORM for databases
sqlc	-	1	SQL code generator, type-safe
Cobra	-	1	CLI framework
testify	-	1	Testing assertions and mocks

Go Deployment:

Method	Tier	Notes
Static binary	1	Go's default, smallest images
CGO (C interop)	2	Requires libc, supported but watch binary size
Go modules	1	Dependency management, lock files

Java

Version	Tier	Test Coverage	Support Ends	Notes
21 LTS	1	Full	Sept 2026+	Current LTS (11-year support)
17 LTS	1	Full	Sept 2026	Previous LTS (10-year support)
11 LTS	2	Community	Sept 2026	Oldest supported LTS
8 LTS	3	None	Dec 2030	EOL commercially, use 11+

Java Framework Compatibility:

Framework	Version	Tier	Notes
Spring Boot	3.x	1	Enterprise app framework, tested end-to-end
Spring Boot	2.x	2	Older version, still common
Spring Data	3.x	1	Data access abstraction
Hibernate	6.x	1	ORM
Micronaut	4.x	1	Lightweight, fast startup
Quarkus	3.x	1	Container-native, GraalVM tested
Dropwizard	4.x	2	REST services framework
Play Framework	2.x	2	Web framework (legacy)
Vert.x	4.x	1	Async toolkit
JUnit 5	-	1	Testing framework
Mockito	-	1	Mocking library

Java Runtime Options:

Option	Tier	Notes
Hotspot JVM	1	Default, fully supported
G1GC (garbage collector)	1	Default in modern Java, tested
ZGC	1	Low-latency GC, supported
Serialization	1	Works, but JSON preferred for APIs
Maven	1	Build tool, dependency management
Gradle	1	Build tool, supported

Rust

Version	Tier	Test Coverage	Support Ends	Notes
1.75+	1	Full	Current stable released every 6 weeks
MSRV (1.70)	1	Full	Minimum supported Rust version

Rust Framework Compatibility:

Framework	Version	Tier	Notes
Actix-web	4.x	1	Web framework, async/await, performance tested
Axum	0.7+	1	Typed web framework
Rocket	0.5.x	2	Web framework (slower compilation)
Tokio	1.x	1	Async runtime
Serde	-	1	Serialization framework
sqlx	-	1	SQL toolkit, compile-time checking
diesel	-	1	ORM

Rust Deployment:

Method	Tier	Notes
Static binary	1	Rust's default, excellent for containers
musl builds	3	Rust supports, but CleanStart uses GLIBC (use gnu target)
Cargo	1	Package manager, lock files standard

.NET

Version	Tier	Test Coverage	Support Ends	Notes
.NET 8	1	Full	Nov 2026	Current LTS
.NET 7	2	Community	May 2024	Maintenance, approaching EOL
.NET 6	2	Community	Nov 2024	LTS, still supported
.NET Framework 4.x	3	None	Windows only, not applicable

.NET Framework Compatibility:

Framework	Version	Tier	Notes
ASP.NET Core	8.x	1	Web framework, full tested stack
Entity Framework Core	8.x	1	ORM
NUnit	-	1	Testing framework
xUnit	-	1	Testing framework

Ruby

Version	Tier	Test Coverage	Support Ends	Notes
3.3	1	Community	3 years after release	Current stable
3.2	1	Community	3 years after release	Previous stable
3.1	2	Community	3 years after release	Older, approaching EOL
3.0	2	Community	EOL April 2024	Legacy, migrate to 3.2+

Ruby Framework Compatibility:

Framework	Version	Tier	Notes
Rails	7.x	1	Full-stack web framework
Rails	6.x	2	Older version, still common
Sinatra	3.x	1	Lightweight web framework
Sidekiq	7.x	1	Background job processing
Bundler	2.x	1	Dependency management
RSpec	3.x	1	Testing framework

PHP

Version	Tier	Test Coverage	Support Ends	Notes
8.3	1	Community	Dec 2025	Current stable
8.2	1	Community	Dec 2024	LTS, long support
8.1	2	Community	Nov 2023	Older, approaching EOL
8.0	3	None	Nov 2023	EOL
7.x	3	None	EOL	Migrate to 8.2+

PHP Framework Compatibility:

Framework	Version	Tier	Notes
Laravel	10.x	1	Full-stack framework, community tested
Symfony	7.x	1	Component-based framework
WordPress	6.x	1	CMS (heavy on packages)
Composer	2.x	1	Dependency management
PHPUnit	11.x	1	Testing framework

Database Client Matrix

SQL Databases

Database	Client Library	Language	Tier	Notes
PostgreSQL	psycopg2	Python	1	Native GLIBC support
PostgreSQL	libpq	Any	1	Native C library
PostgreSQL	pg	Node.js	1	Pure JS, tested
PostgreSQL	pq	Go	1	Pure Go, tested
PostgreSQL	JDBC	Java	1	Java driver, tested
MySQL	mysqlclient	Python	1	Native, but consider PyMySQL
MySQL	PyMySQL	Python	1	Pure Python, slower but compatible
MySQL	mysql2	Node.js	1	Fast native driver
MySQL	go-sql-driver	Go	1	Pure Go, tested
MySQL	JDBC	Java	1	MySQL JDBC driver
SQLite	sqlite3	Python	1	Built-in, file-based
SQLite	better-sqlite3	Node.js	1	Fast synchronous driver
SQLite	stdlib	Go	1	CGO-based, works
MariaDB	mysql2	Node.js	1	MySQL-compatible
MariaDB	PyMySQL	Python	1	Compatible

NoSQL Databases

Database	Client Library	Language	Tier	Notes
Redis	redis-py	Python	1	Fully tested
Redis	ioredis	Node.js	1	Async, typed
Redis	go-redis	Go	1	Fully featured
Redis	Jedis	Java	1	Standard driver
MongoDB	pymongo	Python	2	Works, community tested
MongoDB	mongoose	Node.js	2	ODM, community tested
MongoDB	go.mongodb.org/mongo-driver	Go	2	Official driver, less tested
MongoDB	MongoDB JDBC	Java	2	Official driver
Elasticsearch	elasticsearch-py	Python	2	API client, community tested
Elasticsearch	@elastic/elasticsearch	Node.js	2	Official client
Cassandra	cassandra-driver	Python	3	Should work, not tested
DynamoDB	boto3	Python	2	AWS SDK, tested with real DynamoDB
DynamoDB	aws-sdk-js-v3	Node.js	2	AWS SDK

Operating System Compatibility

CleanStart images run on any GLIBC-based Linux host. Here's tested coverage:

Host OS	Version	Tier	Container Runtime	Notes
Ubuntu	22.04 LTS	1	Docker, containerd, Podman	Primary test target
Ubuntu	20.04 LTS	1	Docker, containerd, Podman	Still widely used, supported
Ubuntu	24.04 LTS	1	Docker, containerd, Podman	New LTS, tested
Debian	12 (Bookworm)	1	Docker, containerd, Podman	Current stable
Debian	11 (Bullseye)	2	Docker, containerd, Podman	Previous stable
RHEL	9.x	1	podman, Docker	Enterprise target
RHEL	8.x	2	podman, Docker	Still common, supported
CentOS	9 Stream	2	podman, Docker	RHEL-compatible
CentOS	8 Stream	3	podman, Docker	EOL, use Stream 9+
Amazon Linux	2023	1	Docker, containerd	AWS standard
Amazon Linux	2	2	Docker, containerd	Previous version
Fedora	39+	2	podman, Docker	Cutting edge, may have issues
Fedora	38	2	podman, Docker	Stable, tested
SUSE	15.x	2	Docker, containerd	Enterprise, community tested
Oracle Linux	9.x	2	Docker, containerd	RHEL-compatible
Alpine Linux	-	3	docker	musl-based, not GLIBC (workarounds exist)

GLIBC Versions:

CleanStart targets GLIBC 2.31+. All listed OSes have compatible GLIBC versions.

Verify GLIBC compatibility on your host:

ldd --version# Output: ldd (GNU libc) 2.35 (compatible)

Container Runtime Matrix

Runtime	Version	Tier	Kubernetes	Notes
containerd	1.7+	1	Default	CNCF standard, most common in K8s
containerd	1.6	2	Supported	Older version, still works
Docker Engine	24.x	1	Desktop only	Local development, Compose
Docker Engine	23.x	2	Desktop only	Older version, still works
CRI-O	1.28+	1	OpenShift	Kubernetes-focused runtime
CRI-O	1.27	2	OpenShift	Slightly older
Podman	4.x+	2	Rootless possible	Rootless containers, similar to Docker
Podman	3.x	2	With caveats	Older version

Kubernetes Version Matrix

K8s Version	Tier	Release Status	Notes
1.28.x	1	Current	Latest stable release
1.27.x	1	Previous (n-1)	Officially supported
1.26.x	1	Previous (n-2)	Officially supported, approaching EOL
1.25.x	2	n-3	Community tested, approaching EOL
1.24.x	2	n-4	Older, not recommended
<1.24	3	Legacy	Use at your own risk

Kubernetes Features Used by CleanStart:

Feature	K8s Version Required	Tier	Notes
securityContext (runAsNonRoot)	1.19+	1	Standard security
readOnlyRootFilesystem	1.19+	1	All versions support
networkPolicy	1.19+	1	Network segmentation
PodDisruptionBudget	1.21+	1	High availability
Ephemeral containers	1.23+	1	Debugging without shell
seccompProfile	1.19+	1	Syscall filtering
Horizontal Pod Autoscaling	1.19+	1	Scaling on metrics
StatefulSets	1.19+	1	Ordered, stable identities

Known Incompatibilities and Workarounds

1. Alpine Linux (musl) Applications

Problem: CleanStart uses GLIBC, Alpine uses musl libc. Applications compiled for Alpine won't run.

Symptom:

error: /usr/local/bin/myapp: no such file or directory(file exists but can't execute)

Workaround 1: Use GLIBC-compiled binaries

# ❌ WRONG: Alpine binary won't run on GLIBC imageFROM registry.cleanstart.com/python:3.12-stableRUN pip install some-alpine-package  # may not work # ✅ CORRECT: Ensure package is GLIBC-compiledFROM registry.cleanstart.com/python:3.12-stableRUN apk add postgresql-client  # from clnpkgs.clnstrt.dev, GLIBC-based

Workaround 2: Rebuild from source

# ✅ CORRECT: Build application from sourceFROM registry.cleanstart.com/python:3.12-stableCOPY . /appRUN pip install -r requirements.txt

2. Node.js Native Modules (node-gyp)

Problem: Native modules must be compiled for GLIBC, not musl.

Symptom:

Error: Could not locate the bindings fileExpected: /app/node_modules/bcrypt/lib/binding/bcrypt_lib.node

Workaround:

# Ensure native modules are compiled for GLIBC (not Alpine)npm install --build-from-source bcrypt # Or use pre-built binaries compiled for GLIBCnpm install bcrypt@5.1.1  # version with prebuilt GLIBC binaries

3. Python C Extensions (numpy, psycopg2)

Problem: Some Python packages have C extensions. They must be compiled for GLIBC.

Solution:

FROM registry.cleanstart.com/python:3.12-stable # Install build dependenciesRUN apk add --no-cache gcc musl-dev python3-dev # Compile C extensions for GLIBCRUN pip install numpy psycopg2-binary

4. Statically-Linked Binaries

Good news: Static binaries work perfectly with CleanStart.

# ✅ WORKS: Static binaries from Go, Rust, etc.FROM registry.cleanstart.com/golang:1.22-staticCOPY ./myapp-static /app/myappENTRYPOINT ["/app/myapp"]

Static binaries don't need any GLIBC (they're self-contained), so they're ideal for minimal, secure images.

5. GUI/X11 Applications

Problem: CleanStart is server-focused, no X11 stack.

Solution: Use host's display server if needed for testing:

# Display tunneling (not recommended for production)docker run --rm -e DISPLAY=:0 \  -v /tmp/.X11-unix:/tmp/.X11-unix \  registry.cleanstart.com/python:3.12-stable \  python3 -m tkinter

Most applications should avoid GUI dependencies.

6. Shell Depending Applications

Problem: Some legacy applications assume a shell exists.

Example:

# Fails in CleanStart (no shell)system("echo hello")

Solution:

# ✅ CORRECT: Use subprocess instead of shellimport subprocessresult = subprocess.run(['echo', 'hello'], capture_output=True)

Reporting Compatibility Issues

If you find an incompatibility, first verify the runtime/framework version since older versions may have different requirements. Check release notes to see if this is a known issue. Reproduce the problem with a minimal example to isolate the issue. Report to CleanStart and include the image version used, framework/library and version, minimal reproduction case, error message and logs, and host OS and container runtime.

Report template:

Title: [Framework] [Version] incompatibility Image: registry.cleanstart.com/python:3.12-stableFramework: Django 4.2.7Container Runtime: Docker 24.0.6Host OS: Ubuntu 22.04 Issue:[Description] Reproduction:[Steps to reproduce] Expected:[What should happen] Actual:[What happens instead] Error:[Full error message]

Testing Your Framework

Before deploying to production, use this testing script to validate your framework's compatibility:

#!/bin/bash# test-compatibility.sh IMAGE="registry.cleanstart.com/python:3.12-stable" # 1. Start containerdocker run -d --name compat-test $IMAGE sleep 1000 # 2. Copy your appdocker cp . compat-test:/app # 3. Install dependenciesdocker exec compat-test pip install -r /app/requirements.txt # 4. Run your app's testsdocker exec compat-test python -m pytest /app/tests # 5. Check exit codeif [ $? -eq 0 ]; then  echo "Compatibility test passed"else  echo "Compatibility test failed"  docker logs compat-testfi # 6. Clean updocker rm -f compat-test

Performance Characteristics

Startup Time

Framework	Cold Start	Warm Start
Python (Flask)	500-800ms	200-400ms
Node.js (Express)	300-600ms	100-300ms
Go	50-100ms	50-100ms
Java (Spring Boot)	2-5s	2-5s (JVM warmup)
Rust (Actix)	100-200ms	100-200ms

Memory Usage (Idle)

Framework	Memory
Go binary	5-20MB
Node.js app	30-80MB
Python app	50-150MB
Java app	200-500MB
Rust binary	10-50MB

These are typical values. Your app may vary significantly based on loaded libraries and configuration.

Version Compatibility Quick Reference

In a hurry? Use these versions:

Python: 3.12 (latest), 3.11 (LTS), 3.10 (migration path)Node.js: 20 LTS (latest), 18 LTS (previous)Go: 1.22+ (latest 2-3 versions)Java: 21 LTS (11-year support), 17 LTS (10-year support)Rust: Latest stable (6-week release cycle).NET: 8 LTS, 6 LTSRuby: 3.3, 3.2PHP: 8.3, 8.2 LTS

What to Read Next

To deepen your knowledge, explore the Security Testing Playbook to verify framework security properties, review Enterprise Image Governance documentation to learn about managing multiple framework versions, and check out the Kubernetes-Helm Operations guide for deploying at scale across frameworks.