DEV Community: Jonathan Pitter

I Detect 26 Frameworks Without AI. Here's How Deterministic File-Based Detection Works.

Jonathan Pitter — Mon, 27 Apr 2026 15:00:00 +0000

When I built Staxa, a platform that deploys isolated customer environments from source code, I needed to answer a deceptively hard question.

"The user pushed a GitHub repo with no Dockerfile. What framework is this, and how do I containerize it?"

The "easy" answer is to "call an LLM." Send the file listing, maybe the first 50 lines of the main config file, and ask it to identify the framework and generate a Dockerfile.

I tried this approach early on and rejected it. Here's why, and what I built instead.

Why Not an LLM?

Three reasons, all deal-breakers for a deployment pipeline:

Latency. Staxa promises a running tenant environment in ~60 seconds. That's 7 pipeline stages: provision, detect, generate, build, deploy, route, health check. An LLM API call adds 2-5 seconds of latency to the detection stage alone. On a bad day, you're waiting for rate limits or retries. For something that should take milliseconds, that's unacceptable.

Cost at scale. Every deployment triggers a detection. At scale, thousands of API calls per month for a task that's fundamentally pattern matching. The cost scales linearly with deployments for no good reason.

External dependency in a critical path. If the LLM provider has an outage, your deployment pipeline stops. For a platform that automates infrastructure provisioning, adding a third-party API call to the critical path is a liability. The platform is designed to minimize external dependencies, the fewer things that can go down, the more reliable the pipeline.

Deterministic file-based detection solves all three: sub-millisecond execution, zero marginal cost, zero external dependencies.

The Detection System: Three Phases

The FrameworkDetector receives a cloned repo directory and returns a DetectResult:

type DetectResult struct {
    Framework  string            // "nextjs", "django", "go", etc.
    Confidence string            // "high" or "medium"
    DetectedBy string            // "found next.config.js" or "found \"next\" in package.json"
    Metadata   map[string]string // Framework-specific extras
}

Detection runs in three phases, each more expensive than the last. If a phase finds a match, the remaining phases are skipped.

Phase 1: Root File Markers (High Confidence)

The cheapest check. Read the root directory listing (one syscall) and look for framework-specific marker files.

// Phase 1: root file markers (high confidence).
for _, fw := range priorityOrder {
    tmpl, ok := templates[fw]
    if !ok || tmpl.Alias != "" {
        continue
    }
    for _, marker := range tmpl.DetectFiles {
        if rootFiles[marker] {
            result = &DetectResult{
                Framework:  fw,
                Confidence: "high",
                DetectedBy: fmt.Sprintf("found %s", marker),
                Metadata:   make(map[string]string),
            }
            break
        }
    }
    if result != nil {
        break
    }
}

Each framework defines its own marker files in the database. For example:

Framework	Marker Files
Next.js	`next.config.js`, `next.config.mjs`, `next.config.ts`
Nuxt	`nuxt.config.js`, `nuxt.config.ts`
Rails	`bin/rails`
Go	`go.mod`
Django	`manage.py`
Spring Boot	`pom.xml`, `build.gradle`, `build.gradle.kts`

If the repo root contains next.config.js, we know it's Next.js with high confidence. No file contents need to be read.

Phase 2: Dependency Markers (Medium Confidence)

If no root file marker matches, we open dependency files and search for framework-specific packages.

// Phase 2: dependency markers (medium confidence).
for _, fw := range priorityOrder {
    tmpl, ok := templates[fw]
    if !ok || tmpl.Alias != "" {
        continue
    }
    for depFile, packages := range tmpl.DetectDeps {
        if !rootFiles[depFile] {
            continue
        }
        content, err := readFileContent(filepath.Join(repoDir, depFile))
        if err != nil {
            continue
        }
        for _, pkg := range packages {
            if containsDependency(depFile, content, pkg) {
                result = &DetectResult{
                    Framework:  fw,
                    Confidence: "medium",
                    DetectedBy: fmt.Sprintf("found %q in %s", pkg, depFile),
                    Metadata:   make(map[string]string),
                }
                break
            }
        }
    }
}

The dependency matching is format-aware. containsDependency knows that package.json is JSON (check for a key), Cargo.toml is TOML (check for a dependency line), and Gemfile is plain text (case-insensitive search). It understands the structure well enough to avoid false positives.

Examples:

Framework	Dependency File	Package to Find
Fastify	`package.json`	`fastify`
Express	`package.json`	`express`
Actix	`Cargo.toml`	`actix-web`
Phoenix	`mix.exs`	`phoenix`
Rails	`Gemfile`	`rails`

This phase is "medium confidence" because a dependency file tells you what libraries are installed, but not necessarily which one is the primary framework. A repo with both express and next in package.json is Next.js, not Express, which is where priority ordering comes in.

Phase 3: Deep Scan (.NET Projects)

Some frameworks don't follow the "config file in root" convention. .NET projects bury their .csproj or .fsproj files in subdirectories, for example, src/MyApp/MyApp.csproj. Phase 3 does a shallow directory walk to find them:

// Phase 3: shallow scan for .NET projects in subdirectories.
if result == nil {
    if projectFile, err := findDotnetProject(repoDir); err == nil && projectFile != "" {
        result = &DetectResult{
            Framework:  "dotnet",
            Confidence: "high",
            DetectedBy: fmt.Sprintf("found %s", projectFile),
            Metadata:   map[string]string{"project_file": projectFile},
        }
    }
}

This is the most expensive phase (directory traversal), so it only runs when phases 1 and 2 found nothing.

The Priority System: Resolving Ambiguity

What happens when a repo has both go.mod and package.json? Or both rails and sinatra in the same Gemfile?

The detector iterates frameworks in a fixed priority order, most specific first:

var priorityOrder = []string{
    "nextjs", "nuxt", "svelte", "remix", "nestjs",
    "phoenix",
    "rails", "sinatra",
    "django", "fastapi", "flask",
    "laravel",
    "actix", "axum",
    "spring-boot",
    "dotnet",
    "go",
    "fastify", "express",
}

The ordering is deliberate:

Frontend meta-frameworks first. Next.js, Nuxt, SvelteKit, and Remix are checked before their underlying runtimes. A Next.js project has both next.config.js and package.json; if Express were checked first, it would incorrectly match on package.json.

Full-stack frameworks before micro-frameworks. Rails before Sinatra. Django before Flask.
Phoenix before generic Elixir. A repo with both rails and sinatra in the Gemfile gets
detected as Rails because Rails is checked first in Phase 2 priority order.

Go and generic Node last. go.mod and package.json are present in many polyglot repos. They're the catch-all; if nothing more specific matches, these are the right fallbacks.

The priority list is evaluated in the same order for both Phase 1 (file markers) and Phase 2 (dependency markers). The first framework to match in priority order wins.

Metadata Enrichment: Framework-Specific Intelligence

After detection, the system enriches the result with framework-specific metadata that the Dockerfile generator needs:

func (d *FrameworkDetector) enrichMetadata(result *DetectResult, repoDir string) {
    switch result.Framework {
    case "nextjs":
        if !inspectNextStandalone(repoDir) {
            result.Metadata["template_override"] = "nextjs_standard"
            result.Metadata["suggest_standalone"] = "true"
        }
    case "actix", "axum":
        if name := parseCargoBinaryName(repoDir); name != "" {
            result.Metadata["binary_name"] = name
        }
    case "dotnet":
        if pf, err := findDotnetProject(repoDir); err == nil && pf != "" {
            result.Metadata["project_file"] = pf
        }
    case "phoenix":
        if name := parseElixirAppName(repoDir); name != "" {
            result.Metadata["binary_name"] = name
        }
    }
}

Next.js: Standalone Detection

Next.js has two deployment modes. The output: 'standalone' config produces a minimal, self-contained build. Without it, you get a full node_modules directory in the image.

The detector inspects the Next config file, strips comment lines to avoid false positives from commented-out config, normalizes whitespace, and checks for the standalone output setting:

func inspectNextStandalone(repoDir string) bool {
    for _, name := range []string{"next.config.js", "next.config.mjs", "next.config.ts"} {
        content, err := readFileContent(filepath.Join(repoDir, name))
        if err != nil {
            continue
        }
        // Strip // line comments to avoid false positives
        var uncommented strings.Builder
        for _, line := range strings.Split(content, "\n") {
            trimmed := strings.TrimSpace(line)
            if strings.HasPrefix(trimmed, "//") {
                continue
            }
            uncommented.WriteString(line)
        }
        normalized := strings.ReplaceAll(uncommented.String(), " ", "")
        if strings.Contains(normalized, "output:'standalone'") ||
            strings.Contains(normalized, `output:"standalone"`) {
            return true
        }
    }
    return false
}

If standalone isn't configured, the detector sets template_override: "nextjs_standard" so the Dockerfile generator uses a different template and emits a suggestion to the user:

Tip: Add output: 'standalone' to your next.config.js for smaller, optimized images

Rust: Binary Name from Cargo.toml

Rust builds produce a binary named after the [package] name in Cargo.toml. The Dockerfile template needs this name to copy the correct binary from the builder stage. The detector parses it out:

func parseCargoBinaryName(repoDir string) string {
    content, err := readFileContent(filepath.Join(repoDir, "Cargo.toml"))
    if err != nil {
        return ""
    }
    inPackage := false
    for _, line := range strings.Split(content, "\n") {
        trimmed := strings.TrimSpace(line)
        if strings.HasPrefix(trimmed, "[") {
            inPackage = trimmed == "[package]"
            continue
        }
        if inPackage && strings.HasPrefix(trimmed, "name") {
            parts := strings.SplitN(trimmed, "=", 2)
            if len(parts) == 2 {
                return strings.Trim(strings.TrimSpace(parts[1]), "\"'")
            }
        }
    }
    return ""
}

Without this, the Dockerfile would use a generic binary name and the build would fail at the COPY --from=builder stage when the binary doesn't exist at the expected path.

Everything Lives in the Database

Here's the design decision that ties this all together: every detection rule, every Dockerfile template, and every default is stored in the platform_config database table as JSONB.

INSERT INTO platform_config (key, value, description) VALUES
('dockerfile_templates.nextjs', '{
  "description": "Next.js (Node.js)",
  "detect_files": ["next.config.js", "next.config.mjs", "next.config.ts"],
  "detect_deps": {"package.json": ["next"]},
  "default_port": 3000,
  "default_build_cmd": "npm run build",
  "default_start_cmd": "npm start",
  "template": "FROM node:{{.RuntimeVersion}}-alpine AS deps\n..."
}', 'Dockerfile template for Next.js applications');

Each framework entry contains:

detect_files: root file markers for Phase 1
detect_deps: dependency file → package name mappings for Phase 2
template: Go text/template string for Dockerfile generation
default_port, default_build_cmd, default_start_cmd: defaults that can be overridden per-deployment An operator can add support for a new framework or modify detection rules for an existing one with a single database insert. No code changes. No redeployment. The detector loads all templates from the database on every detection run.

Framework aliases handle sub-frameworks that share the same Dockerfile template. Gin, Fiber, Echo, and Chi all alias to the go template:

INSERT INTO platform_config (key, value, description) VALUES
('dockerfile_templates.gin',   '{"alias": "go"}', 'Alias → dockerfile_templates.go'),
('dockerfile_templates.fiber', '{"alias": "go"}', 'Alias → dockerfile_templates.go'),
('dockerfile_templates.echo',  '{"alias": "go"}', 'Alias → dockerfile_templates.go'),
('dockerfile_templates.chi',   '{"alias": "go"}', 'Alias → dockerfile_templates.go');

From Detection to Dockerfile

Once the framework is detected, the DockerfileGenerator takes over:

gen := builder.NewDockerfileGenerator(cfg.Store)
tmpl, err := gen.LoadTemplate(ctx, templateKey)
// ...
rendered, err := gen.Generate(tmpl, builder.DockerfileVars{
    RuntimeVersion: runtimeVersion,
    Port:           svc.Port,
    Framework:      result.Framework,
    AppName:        svc.Name,
    BinaryName:     result.Metadata["binary_name"],
    ProjectFile:    result.Metadata["project_file"],
})

The template variables flow through naturally:

{{.RuntimeVersion}}: pinned per-service, or falls back to a sensible default (Node 20, Python 3.12, Go 1.23, etc.)
{{.Port}}: from service config, or the template's default_port
{{.BinaryName}}: parsed from Cargo.toml or mix.exs by the metadata enrichment phase
{{.ProjectFile}}: the relative path to the .csproj for .NET projects The generated Dockerfile is then passed to the Buildah build pipeline (covered in the previous post) as if the user had written it themselves.

The Dashboard Integration: Real-Time Detection

Detection doesn't just happen at build time. When a user connects a GitHub repo in the dashboard wizard, the Go API runs the same detection logic against the GitHub API, before any code is cloned:

func (s *Server) handleAnalyzeRepo(w http.ResponseWriter, r *http.Request) {
    // 1. Get root tree via GitHub API
    tree, _ := s.githubApp.GetTree(ctx, installationID, owner, repo, branch)

    // 2. Determine which dependency files to fetch
    filesToFetch := ghpkg.DetectFilesToFetch(tree)

    // 3. Fetch them in parallel (bounded to 4 concurrent requests)
    fileContents := s.fetchFilesParallel(ctx, installationID,
        owner, repo, branch, filesToFetch)

    // 4. Detect framework from the fetched contents
    fwResult := ghpkg.DetectFrameworkFromDeps(tree, fileContents)
}

The parallel file fetching uses a bounded semaphore pattern, up to 4 concurrent GitHub API calls:

sem := make(chan struct{}, 4) // bounded concurrency

for _, name := range files {
    wg.Add(1)
    go func(filename string) {
        defer wg.Done()
        sem <- struct{}{}
        defer func() { <-sem }()

        content, err := s.githubApp.GetFileContent(ctx,
            installationID, owner, repo, filename, branch)
        if err != nil {
            return // Non-fatal — skip files we can't fetch
        }

        mu.Lock()
        results[filename] = []byte(content)
        mu.Unlock()
    }(name)
}

The result appears instantly in the wizard UI: the framework card gets an "Auto-detected" badge, the runtime version auto-populates, and the user can override any of these before deploying.

The Fallback Strategy

What if detection fails? The platform has a configurable fallback strategy, stored in ... you guessed it, the database:

INSERT INTO platform_config (key, value, description) VALUES
('dockerfile_gen.fallback_strategy', '"error"',
 'What to do when framework is unknown and no Dockerfile: "error" or "generic_node"');

In "error" mode (the default), the deploy fails with a clear message telling the user to add a Dockerfile. In "generic_node" mode, it falls back to a generic Node.js Express template, a reasonable bet for repos where package.json exists but no specific framework was identified.

The fallback result is clearly marked:

result = &builder.DetectResult{
    Framework:  "express",
    Confidence: "low",
    DetectedBy: "fallback:generic_node",
    Metadata:   make(map[string]string),
}

The "low" confidence and "fallback:generic_node" detection source are both surfaced to the user via SSE events, so there's no silent guessing.

The Numbers

Metric	Value
Frameworks detected	26
Dockerfile templates	19 (+ 7 aliases)
Detection phases	3 (file markers → deps → deep scan)
Confidence levels	3 (high, medium, low/fallback)
External API calls	0
Detection time	Sub-millisecond (after clone)
Template variables	8 (RuntimeVersion, Port, BuildCommand, StartCommand, Framework, AppName, BinaryName, ProjectFile)
Configuration	100% database-driven, zero hardcoded rules

Try It

Push a repo with no Dockerfile and watch the detection work in real-time through the dashboard wizard or SSE event stream.

👉 Join the waitlist at staxa.dev

This is the third post in the Building Staxa series. Previously: the multi-tenancy problem and the Buildah build pipeline. Next up: how Kubernetes NetworkPolicies, ResourceQuotas, and namespace isolation create real tenant boundaries, and why tenant_id columns aren't enough.

Kaniko Is Dead. Here's How I Build Tenant Images in Kubernetes Now.

Jonathan Pitter — Tue, 21 Apr 2026 15:00:00 +0000

Google archived Kaniko in June 2025. Docker-in-Docker requires privileged containers. I needed a third option for my project so I built a Buildah-based image pipeline that runs as Kubernetes Jobs, clones source, auto-generates Dockerfiles, and pushes to a private registry. Here's exactly how it works.

If you're building container images inside a Kubernetes cluster in 2026, your options have narrowed faster than you might think.

Docker-in-Docker requires mounting the Docker socket or running privileged containers, effectively giving the build container root access to the host. Every security guide tells you not to do this. OWASP's Docker Security Cheat Sheet says it plainly says it plainly: "Do not run containers with the --privileged flag."

Kaniko was the answer for years, Google's purpose-built tool for building images inside unprivileged containers. No Docker daemon needed. Then in June 2025, Google archived the repository. It's now read-only. GitLab has already removed their Kaniko documentation and recommends Buildah or Podman instead.

I was building Staxa, a multi-tenant PaaS that provisions isolated customer environments via API and I needed an image build pipeline that would run reliably inside k3s on a single ARM64 server. I started with Kaniko, saw the writing on the wall, and switched to Buildah.

This post is a walkthrough of how that pipeline actually works.

The Problem: Building Tenant Images From Source

When a Staxa user deploys an app, here's what happens at the build stage:

User pushes source code (GitHub repo) or provides a Dockerfile
The platform needs to turn that source into a container image
The image gets pushed to an internal registry
The orchestrator deploys it into the tenant's isolated namespace All of this happens inside a Kubernetes cluster. There's no external CI service, no GitHub Actions, no cloud build service. The build runs as a Kubernetes Job in the staxa-system namespace.

The constraints:

Must work on a single-node k3s cluster (ARM64)
Must handle private GitHub repos (token injection)
Must support auto-generated Dockerfiles (framework detection feeds into this)
Must clean up after itself (no build job accumulation)
Must surface build logs back to the user on failure

Why Buildah

After Kaniko's archival, three alternatives emerged as the main contenders:

BuildKit: Docker's modern build backend. Fast, parallel DAG-based execution and great caching. But running BuildKit as a standalone service inside Kubernetes adds another long-lived component to manage. For a platform that values minimal moving parts, that's overhead I didn't want.

Buildah: Red Hat's OCI image builder, now part of the Podman Container Tools suite accepted into the CNCF Sandbox in January 2025. Buildah builds standard Dockerfiles, pushes to any registry, and runs as a one-shot process, no daemon required. It fits naturally into the Kubernetes Job model: spin up a pod, build, push, exit.

werf / Kimia: Higher-level tools that wrap Buildah or BuildKit. More features, more opinions, more dependencies. Not what I wanted for a platform where every external dependency is a liability.

Buildah won because it maps cleanly onto a single pattern: one Kubernetes Job per build, no persistent infrastructure.

The Architecture

staxa-system namespace

staxad (Go API) receives deploy request

Creates a Kubernetes Job running Buildah

Job clones repo → builds image → pushes to registry

Go API polls Job status until success or failure

On failure: captures last 50 lines of build logs

On completion: cleans up the Job

The Go API orchestrates everything through client-go. No shell scripts wrapping kubectl. No Helm charts. The builder is a Go struct that implements a Builder interface:

type Builder interface {
    Build(ctx context.Context, job BuildJob) (imageTag string, err error)
}

This interface is the seam that let me swap Kaniko for Buildah without touching the rest of the pipeline. The deploy pipeline calls builder.Build() and gets back an image tag. It doesn't know or care which tool actually built the image.

The Build Job

Here's what the Buildah Kubernetes Job looks like when the Go API creates it:

bJob := &batchv1.Job{
    ObjectMeta: metav1.ObjectMeta{
        Name:      jobName, // "build-dep_abc123"
        Namespace: "staxa-system",
        Labels:    map[string]string{
            "staxa.dev/deployment-id": job.DeploymentID,
        },
    },
    Spec: batchv1.JobSpec{
        BackoffLimit: &zero, // No retries — fail fast
        Template: corev1.PodTemplateSpec{
            Spec: corev1.PodSpec{
                RestartPolicy: corev1.RestartPolicyNever,
                Containers: []corev1.Container{{
                    Name:    "buildah",
                    Image:   cfg.BuilderImage,
                    Command: []string{"sh", "-c", buildScript()},
                    Env:     env,
                    SecurityContext: &corev1.SecurityContext{
                        RunAsUser: &rootUser,
                        Capabilities: &corev1.Capabilities{
                            Add: []corev1.Capability{
                                "CHOWN",
                                "DAC_OVERRIDE",
                                "FOWNER",
                                "SETUID",
                                "SETGID",
                                "SETFCAP",
                                "SYS_CHROOT",
                            },
                        },
                    },
                }},
            },
        },
    },
}

So I made a few deliberate choices here:

BackoffLimit: 0: If a build fails, it fails. No automatic retries that could mask a real error. The user sees the failure immediately via SSE events and gets build logs.

RestartPolicy: Never: Same philosophy. The Job runs once. If something goes wrong, the user redeploys with a fix rather than the platform silently retrying with the same broken code.

Minimal capabilities: Instead of running the build container with full privileges, only seven specific Linux capabilities are granted: CHOWN, DAC_OVERRIDE, and FOWNER for file ownership during COPY --chown; SETUID and SETGID for USER directives; SETFCAP for file capabilities in base images; and SYS_CHROOT for Buildah's chroot isolation mode. This is the minimum set that lets Buildah build arbitrary Dockerfiles.

Labels: Every build Job is labeled with the deployment ID. This is how we find the associated pods later when we need to grab logs from a failed build.

The Build Script

The actual build runs as a shell script inside the Buildah container:

set -e

# Inject GitHub token for private repos if available
CLONE_URL="$REPO_URL"
if [ -n "${GITHUB_TOKEN:-}" ]; then
  CLONE_URL="$(echo "$REPO_URL" | \
    sed "s|https://|https://x-access-token:${GITHUB_TOKEN}@|")"
fi

# Shallow clone — only the branch we need, one commit deep
git clone --depth 1 --branch "$BRANCH" "$CLONE_URL" /workspace
cd /workspace

# Build with VFS storage driver + chroot isolation (no privileged mode needed)
buildah --storage-driver vfs build \
  --isolation chroot \
  --layers \
  $BUILD_ARGS \
  --tag "$IMAGE_TAG" \
  --file "$DOCKERFILE_PATH" \
  "${BUILD_CONTEXT:-.}"

# Push to internal registry (TLS disabled for in-cluster registry)
buildah --storage-driver vfs push \
  --tls-verify=false \
  "$IMAGE_TAG" \
  "docker://$IMAGE_TAG"

--storage-driver vfs: This is the key to running Buildah without overlayfs kernel support. VFS copies each layer fully rather than using filesystem overlays. It's slower than overlayfs, but it works everywhere including inside a container on k3s on an ARM64 Hetzner box. No special kernel modules required.

--isolation chroot: Instead of spinning up a full OCI runtime (runc) for each build step, Buildah uses a simple chroot. This keeps the capability requirements minimal, chroot isolation only needs SYS_CHROOT rather than the broad set of privileges a full OCI runtime would demand.

--layers: Enables layer caching. Subsequent builds reuse unchanged layers, which significantly speeds up redeploys where only application code changed.

--depth 1: Shallow clone. We don't need git history, so we save time and bandwidth by only pulling the latest commit on the target branch.

$BUILD_ARGS: Tenant environment variables are injected as --build-arg flags by the Go API. This is critical for frameworks like Next.js that inline NEXT_PUBLIC_* variables at build time they need to be available during the image build, not just at runtime.

Image Tagging Strategy

Every image is tagged with a deterministic, versioned path:

{registry}/tenants/{tenant_id}/{service_name}:{version}

For example: registry.staxa-system:5000/tenants/ten_abc/app:3

The Go code that generates this:

imageTag := fmt.Sprintf("%s/tenants/%s/%s:%d",
    job.RegistryURL, job.TenantID, name, job.Version)

This gives us:

Tenant isolation in the registry: each tenant's images live under their own path
Multi-service support: a tenant with a frontend and backend gets separate image paths
Version history: rollback is just redeploying a previous version number
No tag collisions: version is an incrementing integer from the database

GitHub Token Resolution

Private repos need authentication. Staxa handles this with a two-tier fallback:

func (b *BuildahBuilder) resolveGitHubToken(ctx context.Context, token string) []corev1.EnvVar {
    // Tier 1: Per-deployment token (from GitHub App installation)
    if token != "" {
        return []corev1.EnvVar{{Name: "GITHUB_TOKEN", Value: token}}
    }

    // Tier 2: Cluster-level secret (for environments without GitHub App)
    _, err := b.client.CoreV1().Secrets(buildahNamespace).
        Get(ctx, "github-credentials", metav1.GetOptions{})
    if err != nil {
        return nil // No token available — public repo only
    }

    return []corev1.EnvVar{{
        Name: "GITHUB_TOKEN",
        ValueFrom: &corev1.EnvVarSource{
            SecretKeyRef: &corev1.SecretKeySelector{
                LocalObjectReference: corev1.LocalObjectReference{
                    Name: "github-credentials",
                },
                Key: "token",
            },
        },
    }}
}

If a GitHub App is configured, each deployment gets a short-lived installation access token (Tier 1). If not, it falls back to a cluster-level secret. If neither exists, the build proceeds without auth which works fine for public repos, fails fast for private ones with a clear error.

Registry Credentials

Similarly, pushing to registries that require auth uses a Docker-compatible credentials mount:

func (b *BuildahBuilder) registryCredentials(ctx context.Context) ([]corev1.Volume, []corev1.VolumeMount) {
    _, err := b.client.CoreV1().Secrets(buildahNamespace).
        Get(ctx, "registry-credentials", metav1.GetOptions{})
    if err != nil {
        return nil, nil // No credentials, internal registry, no auth needed
    }

    volumes := []corev1.Volume{{
        Name: "registry-credentials",
        VolumeSource: corev1.VolumeSource{
            Secret: &corev1.SecretVolumeSource{
                SecretName: "registry-credentials",
            },
        },
    }}
    mounts := []corev1.VolumeMount{{
        Name:      "registry-credentials",
        MountPath: "/root/.docker/config.json",
        SubPath:   "config.json",
        ReadOnly:  true,
    }}
    return volumes, mounts
}

Buildah reads Docker-compatible auth from /root/.docker/config.json, so the same credentials format works for both tools which is another reason the Kaniko → Buildah migration was straightforward.

Polling, Failure Handling, and Cleanup

The Go API doesn't use Kubernetes watches for build status. It polls:

err = wait.PollUntilContextTimeout(ctx, 5*time.Second, 10*time.Minute, false,
    func(ctx context.Context) (bool, error) {
        j, err := b.client.BatchV1().Jobs(buildahNamespace).
            Get(ctx, jobName, metav1.GetOptions{})
        if err != nil {
            return false, err
        }
        if j.Status.Succeeded >= 1 {
            return true, nil
        }
        if j.Status.Failed >= 1 {
            buildErr = fmt.Errorf("buildah: build failed for %s", imageTag)
            if logs := b.tailBuildLogs(ctx, jobName); logs != "" {
                buildErr = fmt.Errorf("%w\nbuild logs:\n%s", buildErr, logs)
            }
            return false, buildErr
        }
        return false, nil
    },
)

Why polling over watches? The build is a synchronous step in an async pipeline. The worker goroutine is already dedicated to this deployment. Polling every 5 seconds for up to 10 minutes is simple, predictable, and doesn't require setting up watch infrastructure. The Kubernetes API handles it fine.

When a build fails, the builder grabs the last 50 lines of logs from the pod:

func (b *BuildahBuilder) tailBuildLogs(ctx context.Context, jobName string) string {
    pods, err := b.client.CoreV1().Pods(buildahNamespace).List(ctx,
        metav1.ListOptions{LabelSelector: "job-name=" + jobName})
    if err != nil || len(pods.Items) == 0 {
        return ""
    }
    tailLines := int64(50)
    req := b.client.CoreV1().Pods(buildahNamespace).
        GetLogs(pods.Items[0].Name, &corev1.PodLogOptions{TailLines: &tailLines})
    rc, err := req.Stream(ctx)
    if err != nil {
        return ""
    }
    defer rc.Close()
    var buf bytes.Buffer
    io.Copy(&buf, rc)
    return buf.String()
}

These logs get surfaced to the user through the SSE event stream. When a build fails, they see exactly why, not a generic "build failed" message.

After every build (success or failure), the Job is deleted:

func (b *BuildahBuilder) cleanupBuildJob(ctx context.Context, jobName string) {
    prop := metav1.DeletePropagationBackground
    b.client.BatchV1().Jobs(buildahNamespace).Delete(ctx, jobName,
        metav1.DeleteOptions{PropagationPolicy: &prop})
}

No TTL controllers, no cron cleanup. The build created the Job, the build cleans it up. Simple.

The Builder Interface Pattern

The reason swapping from Kaniko to Buildah was a one-file change: the Builder interface.

type Builder interface {
    Build(ctx context.Context, job BuildJob) (imageTag string, err error)
}

Both KanikoBuilder and BuildahBuilder implement this interface. The deploy pipeline doesn't know which one is active. Switching was a matter of changing which struct gets instantiated at startup no changes for the pipeline, the worker, or the API handlers.

There's also a NoopBuilder for testing that returns a deterministic image tag without building anything. The entire deployment pipeline can be tested end-to-end without ever running a real build.

What I'd Do Differently

VFS performance. The vfs storage driver works everywhere but copies every layer fully. For a platform optimized for initial deploy speed ("60 seconds to a running tenant"), build time is the largest chunk. I'm exploring whether fuse-overlayfs could work in this environment to speed up builds without requiring privileged overlayfs access.

Build caching across tenants. Currently each build starts fresh. Tenants deploying the same framework (say, Next.js 15) all download and install the same base dependencies independently. A shared cache layer could cut repeat build times significantly.

BuildKit as an alternative. BuildKit's parallel DAG execution would be faster for multi-stage Dockerfiles. If build performance becomes a bottleneck at scale, running a BuildKit daemon as a persistent service in the cluster rather than per-build Jobs would be worth the operational tradeoff.

The Numbers

Metric	Value
Build tool	Buildah (VFS storage driver)
Execution model	One Kubernetes Job per build
Build timeout	10 minutes
Poll interval	5 seconds
Log capture on failure	Last 50 lines
Cleanup	Immediate (background propagation)
Migration from Kaniko	1 file changed, 0 pipeline changes

Try It

Staxa handles the entire build pipeline, framework detection, Dockerfile generation, image building, and deployment all behind a single API call or dashboard wizard.

👉 Join the waitlist at staxa.dev

This is the second post in the Building Staxa series. The first post covered the multi-tenancy problem and why I built a platform that automates full tenant isolation. Next up: how the framework detection system auto-detects 19 frameworks without any AI using deterministic file-marker matching and dependency-file inspection.

There Are 5 Ways to Do Multi-Tenancy. I Automated the Hardest One.

Jonathan Pitter — Wed, 15 Apr 2026 12:00:00 +0000

If you've ever built a SaaS product that serves multiple customers, you've stared at this decision:

How do I keep Customer A's data away from Customer B?

The answer seems simple until you actually try to implement it.

Then you discover that every approach on the multi-tenancy spectrum is a different flavor of pain.

The Multi-Tenancy Spectrum (And Why Every Option Hurts)

Level 1: Shared Database, Shared Schema

The most common starting point. Everyone's data lives in the same tables, separated by a tenant_id column.

-- Every query needs this.
SELECT * FROM orders WHERE id = $1 AND tenant_id = $2;

-- Forget the tenant_id filter once and you have a data breach.
SELECT * FROM orders WHERE id = $1;

It's cheap and simple, until it isn't. A single missed WHERE clause leaks data across tenants. Junior devs joining the team won't always remember. Your ORM might not enforce it. And PostgreSQL itself isn't immune CVE-2024-10976, disclosed in late 2024, showed that row-level security policies could be bypassed when queries were reused across different roles, potentially letting one tenant's query return another tenant's rows.

Then there's the noisy neighbor problem. One tenant runs a massive data import and suddenly every other tenant's dashboard grinds to a halt. You can't set per-tenant resource limits because everyone shares the same compute and storage.

Level 2: Shared Database, Separate Schemas

More isolation as each tenant gets their own schema inside one database. tenant_a.orders, tenant_b.orders.
The problem shifts from simply remembering the where clause to making sure you can coordinate schema migrations across 'N' number of schemas with zero downtime. At 10 tenants, that's manageable. At 500, you've built a migration orchestration system. And tenants still share the underlying database resources, so noisy neighbors are still a thing.

Multiple sources I reviewed while building Staxa recommend avoiding this approach entirely. It combines the operational complexity of separate databases with the resource-sharing downsides of a shared one. You can check this out

Level 3: Database Per Tenant

Now we're getting to real isolation. Each tenant has their own database instance, Backup and restores are on a per-tenant level. A failure in one tenant's database doesn't cascade to others.

But you're now running migrations across 'N' separate databases. Schema version drift becomes a real risk. Your CI/CD pipeline needs to understand which tenants are on which version, infrastructure costs scale linearly and you still haven't isolated the application layer. Your API server is shared, your compute is shared and your networking is shared.

Level 4: Namespace or Container Isolation

Pushing a step further, each tenant runs in their own Kubernetes namespace or container group, with their own database. Now you've isolated compute, storage, and networking.

This is where things get architecturally correct but operationally brutal. You need to automate namespace creation, deploy applications into each one, configure ingress routing per tenant, provision and inject database credentials, set up SSL certificates, manage resource quotas, configure network policies, and wire up health checks, for every single tenant.

Most teams that attempt this build a custom control plane. That control plane becomes its own product to maintain.

Level 5: Fully Siloed, Dedicated Infrastructure Per Customer

The golden standard, each customer gets their own everything

Application
Database
Subdomain
SSL
Network isolation
No shared resources.
No chance of cross-tenant data leakage.
No noisy neighbor issues.

Enterprise customers in regulated industries demand this, Government contracts require it and even B2B SaaS customers increasingly ask for it as a premium tier.

The tradeoff? It's the hardest approach to operationalize by far. Without automation, provisioning a new customer environment typically takes two to six weeks, accounting for infrastructure setup, security configuration, networking, and testing. Supporting one or two dedicated deployments manually is feasible. However supporting ten or more without a purpose-built system requires significant dedicated engineering investment.

This is the problem I decided to solve.

Staxa: Full Tenant Isolation in 60 Seconds

Staxa is an API-first platform that automates Level 5 multi-tenancy. One API call, and ~60 seconds later your customer has:

Their own application container running their framework
A dedicated PostgreSQL or MySQL database
A unique subdomain with automatic SSL via Let's Encrypt
Full Kubernetes namespace isolation: network policies, resource quotas, RBAC
Environment variables encrypted at rest with AES-256-GCM

curl -X POST https://api.staxa.dev/api/v1/tenants \
  -H "Authorization: Bearer sk_live_xxx" \
  -d '{
    "name": "acme-corp",
    "source": {
      "type": "github",
      "repo_url": "https://github.com/acme/app"
    },
    "database": { "engine": "postgres" }
  }'

That's it. Hook this into a Stripe webhook and your SaaS provisions isolated customer environments automatically on payment. No Terraform configs, No DevOps tickets, No two-week onboarding process.
There's also a visual dashboard with a deployment wizard for teams that prefer point-and-click over API calls. Both interfaces hit the same backend, the dashboard just builds the same JSON payload through a multi-step UI flow.

How It Works Under the Hood

The entire platform is a single Go binary (staxad) running on a k3s Kubernetes cluster. When a deploy request comes in, it moves through a 7-stage pipeline:

Provision → Create the Kubernetes namespace, RBAC rules, ResourceQuotas, and NetworkPolicies for the tenant.
Detect → The framework detection system identifies which frameworks your project uses from file markers and dependency files. 26 frameworks supported, deterministic file-based detection with a two-tier confidence system. No external API calls, zero latency overhead, zero external dependencies.
Generate → This one came from a friend but if you have no Dockerfile in your project? Then auto-generate a Dockerfile using Go text/template with framework-specific configs pulled from the database. Ports, health check paths, build commands, start commands, all operator-tunable without code changes.
Build → Buildah runs as a Kubernetes job, builds the image, pushes to the internal registry. No Docker-in-Docker, no privileged containers.
Deploy → Kubernetes Deployment created with resource limits, health checks, and environment variables. Database provisioned in the same namespace if requested.
Route → Traefik IngressRoutes for the tenant's subdomain. cert-manager handles SSL automatically.
Health Check → Poll the health endpoint until the app responds, then mark as ready.

The caller gets real-time progress via Server-Sent Events throughout all seven stages. The dashboard shows a live progress bar; an API consumer streams the same events programmatically.

Hetzner CAX21 (~€8/month) — k3s single-node cluster

staxa-system namespace

staxad — Go API, single binary, 49 endpoints

PostgreSQL — platform database

Redis — job queue + SSE pub/sub

Next.js — dashboard + deployment wizard

tenant-acme namespace

app container (Next.js)

dedicated postgres

tenant-widgetco namespace

frontend service

backend service

dedicated postgres

Traefik — ingress controller, auto-SSL via cert-manager, *.staxa.dev routing

A tenant can have multiple services (frontend + backend) sharing a namespace, internal networking, and database credentials. Service URL injection (STAXA_SERVICE_{NAME}_URL) handles cross-service discovery automatically.

Why Go, Why Kubernetes, Why a $10 Server?

Go because infrastructure tooling lives in Go. Docker, Kubernetes, Terraform, Traefik, Caddy, all Go and I can't help trying new things :).

The client-go library for Kubernetes is first-class. Goroutines handle parallel tenant deployments naturally. And a single compiled binary means the entire control plane is one scp away from running on any server.

Kubernetes (k3s) because the abstractions map perfectly to the multi-tenancy problem.

Namespaces: tenant boundaries.
ResourceQuotas: noisy neighbor prevention.
NetworkPolicies: traffic isolation.
Deployments: rolling updates and rollbacks for free.

I'm not bolting isolation onto a system that wasn't designed for it, I'm using a system where isolation is a first-class primitive.

Hetzner server because the old version of this platform ran on AWS and cost $200+/month with zero tenants deployed, literally just from developing, I almost gave up entirely after that pain. It's the same architecture, databases in containers instead of managed services, commodity ARM compute. The entire platform and 10-15 demo tenants run comfortably on one box.

Design Decisions That Matter

No magic numbers: Every tunable value — resource limits, port ranges, framework templates, detection rules; lives in a platform_config database table. An operator can change any default setting without redeploying the whole platform. This was a hard rule from day one.

No external AI for framework detection: I evaluated using an LLM API to detect project frameworks and rejected it since that would be easier. However the latency, cost, and external dependency were all liabilities. Deterministic file-based detection with parallel file fetching worked out faster, cheaper (the cost would scale with projects deployed), and has no external dependencies.

49 API endpoints across 12 groups: Tenants, deployments, services, domains, environment variables, network rules, container registry credentials, templates, and more.

Dual auth: Clerk JWTs for dashboard users, API keys with prefix lookup for programmatic access.

Multi-service tenants: Staxa models tenants as isolation boundaries that can contain multiple services because real applications have frontends and backends that need to talk to each other.

Who This Is For

SaaS founders whose enterprise customers are asking for dedicated environments. Instead of months of infrastructure work, you integrate one API call into your onboarding flow, that's it.
Agencies who need isolated environments per client, each with their own domain and SSL without one client's traffic spike affecting another.
Platform engineers who need on-demand isolated environments for dev teams or staging, without giving everyone kubectl access.

The Numbers

Metric	Value
Infrastructure cost	~€8/month
Time to provision a fully isolated tenant	~60 seconds
Provider-facing API endpoints	49
Frameworks detected	26
Auto-generated Dockerfile templates	19
External SaaS dependencies	2 (Clerk for auth, Cloudflare for DNS)
V1 AWS cost (zero tenants)	$200+/month

Try It
Staxa is in early access and I'm working directly with early adopters.

👉 Play around and join the waitlist if interested at staxa.dev