feat: Add support for custom Docker image in create command

[asaura08]

This pull request introduces support for specifying a custom Docker image for the Frappe service, along with improvements to the Docker build process and better handling of prebaked app detection. The changes allow users to pass a custom image for Frappe and related services, streamline Docker image building, and improve robustness in app installation and configuration.

Custom Docker image support:

• Added an optional frappe_image parameter to the command-line interface, configuration model (BenchConfig), and TOML export, enabling users to specify a custom Docker image for the Frappe service. This image is propagated to all relevant services in the Docker Compose configuration and worker setup. [1] [2] [3] [4] [5] [6] [7]

Examples:

Create a new custom image

PYTHON_VERSIONS=3.14.2 NODE_VERSIONS=24 PREBAKE_APPS='erpnext:version-16-beta,builder:develop' PREBAKE_FRAPPE_BRANCH=version-16-beta ./build-local.sh --no-cache

Use the new custom image

fm create builder.example.com --environment prod --ssl letsencrypt --letsencrypt-preferred-challenge http01 --letsencrypt-email asaura08@example.com --frappe-branch version-16-beta -a builder --frappe-image frappe-manager-local-frappe:v0.18.0

Docker build process improvements:

• Introduced a new Docker/build-local.sh script to automate local Docker image builds with configurable arguments and architecture detection, supporting prebaked images and custom build parameters.
• Updated Docker/frappe/Dockerfile to use newer versions of pyenv and nvm, and simplified prebake logic by copying the entire frappe-bench directory instead of individual apps. [1] [2]

Prebaked app handling and robustness:

• Improved detection of prebaked apps by reading from a /prebake_info file inside the container, ensuring that only non-prebaked apps are installed during setup. [1] [2]
• Adjusted logic for copying prebaked workspace data to use the correct prebake image reference.

Other improvements:

• Enhanced the helper function for extracting app names from hooks.py to be more robust against formatting variations.
• Refactored exception handling for branch change failures to inherit from the correct base class and support more detailed output control.

Notes:
This PR closes #330 #329
This PR resolves #323 #332

[Copilot]

Pull request overview

This pull request adds support for specifying custom Docker images for Frappe services, enhances the Docker build process with a new local build script, and improves prebaked app detection and handling. The changes enable users to override the default Frappe Docker image while maintaining compatibility with the existing build and configuration workflows.

• Added frappe_image parameter to CLI, configuration model, and compose generation logic
• Introduced build-local.sh script for automated local Docker image builds with configurable parameters
• Improved prebaked app detection by reading /prebake_info file from containers to skip redundant installations

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
frappe_manager/commands.py	Added CLI option for custom frappe Docker image
frappe_manager/site_manager/bench_config.py	Added frappe_image field to config model and image parsing logic for compose inputs
frappe_manager/site_manager/site.py	Added support for applying custom images to compose configuration and fixed prebake image reference
frappe_manager/site_manager/workers_manager/SiteWorker.py	Added logic to apply custom frappe image to worker services
frappe_manager/site_manager/bench_operations.py	Added method to read prebaked apps from container's /prebake_info file
frappe_manager/site_manager/site_exceptions.py	Refactored branch change exception to inherit from correct base class with enhanced output control
Docker/frappe/Dockerfile	Updated pyenv and nvm versions; simplified prebake copying to include entire frappe-bench directory
Docker/frappe/helper-function.sh	Improved app name extraction regex to handle whitespace variations
Docker/build-local.sh	New script for building Docker images locally with architecture detection and configurable build arguments

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The image parsing logic here assumes that image names can only contain one colon. However, Docker images can have registry addresses (e.g., registry.example.com:5000/frappe-manager-local-frappe:v0.18.0), which would cause this code to incorrectly split the image. Consider using rsplit(":", 1) instead to split only on the last colon, or better yet, use a more robust image parsing approach.

Suggested change

	image_name, image_tag = self.frappe_image.split(":", 1)
	# Use rsplit to split on the last colon so registry ports are handled correctly
	image_name, image_tag = self.frappe_image.rsplit(":", 1)

[Copilot]

The build script assumes it will be executed from the Docker directory (since it references images-tag.json and ${image}/. as context paths without any directory prefix). However, there's no documentation or check to ensure the script is run from the correct directory. Consider adding a check at the beginning of the script to verify the working directory or use absolute paths based on the script's location.

[Copilot]

The variable workspace_copy_image is renamed from frappe_image but the logic still attempts to derive the prebake image by replacing '-frappe' with '-prebake'. If a user provides a custom frappe image that doesn't follow the naming convention (e.g., doesn't contain '-frappe' in the name), this replacement will silently fail to produce the expected prebake image name. Consider adding validation or documentation about the expected image naming convention.

Suggested change

	workspace_copy_image = frappe_image.replace('-frappe', '-prebake')
	if "-frappe" not in frappe_image:
	raise BenchException(
	f"Unable to derive workspace prebake image from frappe image '{frappe_image}'. "
	"Expected the image name to contain '-frappe' so it can be replaced with '-prebake'."
	)
	workspace_copy_image = frappe_image.replace("-frappe", "-prebake")

[asieftejani]

Nice @asaura08 are you one of the maintainers this repo?

[asaura08]

Nice @asaura08 are you one of the maintainers this repo?
No, I'm not one of the maintainers but I have a very good knowledge about frappe 😁