dxform

A Dockerfile transpiler that converts between different base systems (e.g., Debian to Alpine) and generates FreeBSD jail configurations.

Features

• Transform base images (Debian, Ubuntu → Alpine, FreeBSD, and reverse)
• Convert package manager commands (apt ↔ apk, apt → pkg) with ~70 package mappings
• Parse shell commands in RUN instructions
• Preserve comments (except inline comments in multiline RUN commands - parser limitation)
• Support multi-stage builds
• Emit to FreeBSD jails (--target freebsd-jail, --target freebsd-build)

The tool also includes basic analyze and validate commands for inspecting Dockerfiles.

Usage

Installation

# Build the binary
go build -o dxform ./cmd/dxform

# Or run directly
go run ./cmd/dxform [command] [flags]

Commands

# Transform to Alpine
dxform transform --target alpine Dockerfile

# Transform to different base systems
dxform transform --target debian Dockerfile
dxform transform --target ubuntu Dockerfile

# Emit to FreeBSD jail configuration
dxform transform --target freebsd-jail Dockerfile > jail.conf

# Emit to FreeBSD build script
dxform transform --target freebsd-build Dockerfile > build.sh

# Analyze Dockerfile structure
dxform analyze Dockerfile

# Validate for issues and best practices
dxform validate Dockerfile

# Use with pipes
cat Dockerfile | dxform transform --target alpine > Dockerfile.alpine

Example

$ dxform transform --target alpine Dockerfile
# Original comments preserved
FROM alpine:3.19
# Install packages with apk
RUN apk update && apk add curl build-base
WORKDIR /app

Limitations

Comment Preservation

Due to the buildkit Dockerfile parser design, inline comments within multiline RUN commands (those using \ line continuations) are stripped during parsing. This is intentional in the upstream parser to maintain backward compatibility.

Comments outside RUN instructions and on single-line RUN commands are fully preserved. Round-trip tests show 99.8%+ structural preservation of the actual Dockerfile semantics.

Package Mappings

The transpiler includes ~70 package mappings between apt and apk. Unmapped packages are passed through unchanged, which may require manual review.

Development

Dependencies

• moby/buildkit - Dockerfile parsing
• mvdan.cc/sh/v3/syntax - Shell command parsing
• cobra - CLI framework

Project Structure

cmd/dxform/          # CLI application and commands
semantic/            # Dockerfile parsing and semantic model
  ├── model.go       # Core BuildGraph and ShellCommand structures
  ├── shell_parser.go # Shell command parsing (mvdan.cc/sh)
transform/           # Transformation and emission logic
  ├── transformation.go # Main transformation engine
  ├── *_transformer.go # Specific transformers (APK, base image, etc.)
emitter/             # Target format emitters
  ├── freebsd/       # FreeBSD jails emitter
testdata/            # Test Dockerfiles
docker-library-test/ # Real-world Dockerfiles for testing
scripts/             # Development scripts (build.sh, test.sh, dev.sh)

Testing

# Quick test suite
./scripts/dev.sh bt

# Full test suite
./scripts/dev.sh btf

# Or use go test directly
go test ./...