Move to Container-Only Distribution for Thunder

[senthalan]

Background

Thunder currently provides both binary and container distributions. However, container-based deployments are becoming the norm. This creates a mismatch: we're optimizing for binary distribution during development, but most production users deploy with containers.

This discussion proposes moving to container-only distribution to align our development practices with how Thunder is actually deployed in production.

Problems with Maintaining Both Distributions

1. Split Focus Hurts Container Experience

When developers have binary distribution as the "easy path," container deployment becomes an afterthought. This means:

• Container-specific issues discovered late (or in production)
• Suboptimal container configurations
• Documentation gaps for Kubernetes/Docker Compose deployments
• Testing primarily happens against binary distribution

Impact: Production deployments (which use containers) get a second-class experience despite being our primary use case.

2. Ecosystem Misalignment: Blocks Default Integration with Modern Tools

Thunder should provide a complete, integrated experience out-of-the-box. However, maintaining binary distribution limits what we can bundle by default because modern cloud-native tools distribute primarily or only via containers.

Concrete example - API Gateway for System APIs:

We want Thunder to ship with built-in API gateway protection for its management and system APIs. This should work out-of-the-box without requiring users to:

• Research and select a compatible gateway
• Separately install and configure it
• Manually set up routing, authentication, and TLS
• Ensure version compatibility

Current reality with binary distribution:

When evaluating gateway options to integrate by default, we face a problem: most modern, actively-maintained API gateways are container-native. We must either:

• Option A: Choose from a limited pool of gateways that support binary distribution (smaller selection, often older projects, may not have features we need)
• Option B: Skip default integration entirely and document manual setup steps (poor user experience, platform-dependent instructions)
• Option C: Build complex wrapper scripts that work differently on Windows/Linux/Mac (high maintenance burden, inconsistent experience)

With container-only distribution:

We can provide docker-compose and Helm charts where Thunder and the gateway work together by default:

# docker-compose.yml - everything pre-configured
services:
  thunder-gateway:
    image: modern-gateway:latest
    ports:
      - "443:443"
    environment:
      - BACKEND_URL=http://thunder-core:9443
    # Pre-configured with TLS, routing, and auth
    
  thunder-core:
    image: wso2/thunder:latest
    # Protected behind gateway, not directly exposed

Users run docker-compose up and get a production-ready setup with the gateway already protecting Thunder's APIs.

Impact:

Binary distribution prevents us from delivering the integrated, secure-by-default experience users expect from a modern IAM platform. Instead of shipping a working solution, we're forced to provide integration documentation and hope users configure it correctly.

Similar limitations affect: Observability tools, secret management, and other cloud-native components we want to bundle for a complete platform experience.

3. Development and Maintenance Overhead

• Maintaining separate Bash and PowerShell scripts
• Testing across multiple OS versions and shell versions
• Two different paths for bug reproduction and fixes
• Divergent configuration approaches (files vs. environment variables)

Impact: Slower feature development and increased maintenance burden.

4. Architectural Misalignment Blocks Microservices Evolution

Future considerations: As Thunder evolves toward microservices architecture, container-first development becomes even more critical. We can't build a microservices platform while optimizing for monolithic binary deployment.

Thunder's roadmap includes separating the core into smaller microservices. Maintaining binary distribution while building microservices creates fundamental conflicts in how we design, test, and deploy each service.

Getting Started Experience Comparison

Binary Approach

• Download and extract the ZIP
• Run the setup script and then the start script

Prerequisites: None
Time to "Hello World": ~2 minutes
Cross-platform: Separate scripts for Linux/Mac (Bash) and Windows (PowerShell)

Container Approach

• Run docker commands to set up and start

Prerequisites: Docker (already installed by most developers)
Time to "Hello World": ~2 minutes
Cross-platform: Identical experience across all operating systems

For production evaluation: docker compose, Helm, or OpenChoreo

Addressing the "Docker Prerequisite" Concern

Reality check: Docker/Docker Desktop installation is now standard for developers:

• Included in most developer workstations
• Available for Windows, Mac, Linux
• Installation is straightforward (single installer)
• Many CI/CD environments have Docker pre-installed

Target audience consideration:

• IAM/security architects evaluating Thunder → likely have Docker
• Platform engineers deploying Thunder → definitely have Docker/Kubernetes
• Developers integrating with Thunder → almost certainly have Docker

For the rare case where Docker isn't available:

• We can provide cloud-based quick start (StackBlitz, GitHub Codespaces)
• Partner organizations can provide hosted demo environments
• Installation documentation for Docker is excellent and widely available

The trade-off:

• Minimal barrier: "Install Docker first" (one-time, 5-10 minutes)
• Significant benefit: Better production experience, faster development, easier integrations

Proposed Path Forward

Container-Only

✅ Pros:

• Aligned with production usage
• Faster development velocity
• Better integration ecosystem access
• Single deployment model to optimize and test
• Cleaner documentation

⚠️ Considerations:

• Docker prerequisite for evaluation

What We Need from This Discussion

1. Do you see use cases we're missing where binary is essential?
2. Concerns about Docker prerequisite for specific user segments?

[JKAUSHALYA]

While I generally support the strategic move to a container-only distribution for Thunder, I have a few practical questions regarding the implementation and its impact on the developer experience:

1. The Debugging Story

• What is the recommended strategy for debugging the application in this new model?
• Will the standard container distribution expose remote debugging ports by default, or will there be a separate "debug" image variant?
• Specifically for contributors: Will we support attaching a debugger to the running container easily (e.g., via IDE configurations), or is the expectation that deep debugging should still happen against a local (non-containerized) build?

2. OS Support & Host Requirements

• One of the arguments for this move is to reduce the "hassle" of maintaining cross-platform compatibility. Does this imply changes to the supported host operating systems for development?
• Are we effectively treating Linux (or Linux-like environments via WSL2) as the primary development target?
• If we are deprioritizing direct binary support, are there specific OSs or environments that will no longer be officially tested or supported for contributors?

3. Hot-Reloading & Filesystem Performance

   Moving to containers often introduces friction with filesystem syncing, particularly on macOS and Windows (Docker Desktop).

• How will this impact features like hot-reloading?
• Have we verified that the volume mount performance is sufficient for a smooth development loop, or will we need specific tooling (like Dev Containers or Mutagen) to mitigate this?

4. Onboarding & Tooling

• Will this change require updates to our repository's tooling?
  Ideally, we should provide a .devcontainer or pre-configured launch.json/docker-compose.yml to ensure that "works on my machine" remains true for new contributors without them needing to manually configure Docker networking and ports.

[senthalan]

Thank you for these thoughtful questions! These are exactly the practical considerations we need to address. Here's how modern container-only projects handle these scenarios, and how we can apply them to Thunder:

1. The Debugging Story

How container-only projects handle this:
Modern container-native projects typically support two debugging approaches:

A. Local Native Debugging (Recommended for Thunder)
Since Thunder is a Go project, developers can run and debug main.go directly without containers for development and debugging:

# Development workflow
go run cmd/thunder/main.go

# Debug in VSCode/GoLand
# Just attach debugger to the Go process as normal

Note: This requires refactoring our bootstrapping logic to work with go run.

B. Remote Debugging (When Container Context Needed)

For scenarios where you need to debug in the actual container environment:

# docker-compose.debug.yml
services:
  thunder-core:
    image: wso2/thunder:dev
    ports:
      - "9443:9443"
      - "40000:40000"  # Delve debugger port
    environment:
      - DEBUG=true
    command: ["dlv", "debug", "--headless", "--listen=:40000", "--api-version=2"]

Recommended approach for Thunder:

Primary: Native Go debugging (go run, IDE debuggers) for 95% of development
Secondary: Docker Compose debug configuration for any advance testing

2. OS Support & Host Requirements

Container-only projects actually expand OS support, not reduce it:

Current State (Binary Distribution):

• Must test: Linux (multiple distros), macOS, Windows
• Must maintain: Bash scripts, PowerShell scripts
• Platform-specific issues: Path separators, environment variables, service management

Container-Only State:

• Development: Any OS that runs Go (Windows, macOS, Linux)
  • Developers run go run main.go natively
  • No WSL2 requirement for development
• Container testing: Any OS with Docker Desktop
  • Windows: Docker Desktop
  • macOS: Docker Desktop
  • Linux: Docker Engine

For Thunder any developers can Run Go natively, test with Docker

3. Hot-Reloading & Filesystem Performance

Modern Go projects don't rely on volume mounts for development or hot reloading features. In Thunder we will also follow this.

For the native Development

# Developer workflow - no containers needed
cd thunder/
# Changes config files
# Changes reflected immediately
go run cmd/thunder/main.go

# Native filesystem, native debugging

4. Onboarding & Tooling

Yes. Pre-configured launch.json/.devcontainer/docker-compose.yml should part of the project and the development guide needs updated.