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 |
| 1 | Standard method, lock files supported |
poetry |
| 1 | Dependency resolution, lock files |
pipenv |
| 2 | Virtual env management (slower on startup) |
uv |
| 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 |
| 1 | Standard, lock files default |
yarn |
| 1 | Alternative, v3+ with corepack |
pnpm |
| 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-basedWorkaround 2: Rebuild from source
# ✅ CORRECT: Build application from sourceFROM registry.cleanstart.com/python:3.12-stableCOPY . /appRUN pip install -r requirements.txt2. 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.nodeWorkaround:
# 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 binaries3. 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-binary4. 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 tkinterMost 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-testPerformance 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 LTSWhat 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.