Optimize bundle size

[kichristensen]

What does this change

This PR introduces an experimental feature flag optimized-bundle-build that reduces bundle image sizes by approximately 54% (from ~446MB to ~204MB) by restructuring how bundles are built.

How it works

The optimization changes the build context and eliminates duplicate layers:

Before (legacy build):

• Build context: project root directory
• Creates duplicate layers: copies .cnab directory twice (once as . then again as .cnab)
• Uses RUN commands to delete files and set permissions (creates additional metadata layers)
• Result: ~446MB bundle images

After (optimized build):

• Build context: .cnab directory
• Uses named build context userfiles to selectively copy user files
• Uses COPY --chown and COPY --chmod to set permissions in a single layer
• Eliminates duplicate 121MB layer from copying .cnab twice
• Eliminates 121MB metadata layer from RUN chgrp/chmod commands
• Result: ~204MB bundle images

Enabling the feature

Set the experimental flag via environment variable:

export PORTER_EXPERIMENTAL=optimized-bundle-build
porter build

Or in your Porter config (~/.porter/config.toml):

experimental = ["optimized-bundle-build"]

Migration for custom Dockerfiles

If you use a custom Dockerfile, you'll need to update the COPY syntax:

Legacy syntax:

COPY . ${BUNDLE_DIR}

Optimized syntax:

COPY --from=userfiles --link . ${BUNDLE_DIR}/

See updated documentation in docs/content/docs/bundle/custom-dockerfile.md for complete migration guide.

Example

# Enable the feature
export PORTER_EXPERIMENTAL=optimized-bundle-build

# Build a bundle
porter build

# Check the resulting image size
docker images | grep mybundle
# Before: mybundle:v0.1.0  446MB
# After:  mybundle:v0.1.0  204MB

What issue does it fix

This is an optimization enhancement that doesn't fix a specific issue. Bundle images can be unnecessarily large due to duplicate layers in the Dockerfile build process. This change provides an opt-in experimental feature to reduce image sizes significantly.

Notes for the reviewer

• The feature is opt-in via experimental flag to maintain backward compatibility
• All existing tests pass in legacy mode (default behavior unchanged)
• Added comprehensive test coverage:
  • Unit tests for both build modes (pkg/build/dockerfile-generator_test.go)
  • Smoke tests validate both modes end-to-end (tests/smoke/*_test.go)
  • Custom Dockerfile handling tested with both modes
• Documentation updated to explain both build modes and migration path
• The optimization eliminates two major sources of bloat:
  1. Duplicate .cnab directory copy (121MB saved)
  2. Metadata layer from RUN chgrp/chmod (121MB saved)

Breaking change considerations:

• Users with custom Dockerfiles will need to update COPY syntax when enabling the flag
• Migration is straightforward and documented
• Legacy mode remains the default until feature is proven stable

Checklist

• Did you write tests?
• Did you write documentation?
• Did you change porter.yaml or a storage document record? Update the corresponding schema file.
• If this is your first pull request, please add your name to the bottom of our Contributors list. Thank you for making Porter better! 🙇‍♀️

[dgannon991]

A couple of questions, happy to be told they're not relevant :D

[dgannon991]

Suggested change

	if _, exists := buildContexts["porter-internal-userfiles"]; exists {
	if _, exists := namedContexts["porter-internal-userfiles"]; exists {

Should this be checking namedContexts instead of buildContexts?