From 34ed7813eec2f2648115beb6061d7f3c668e309f Mon Sep 17 00:00:00 2001 From: root Date: Sat, 9 May 2026 23:35:50 +0000 Subject: [PATCH] docs(docker): document base image approach as deferred due to workspace complexity The base image strategy has been implemented but deferred due to fundamental issues with pnpm workspace structure. All products currently use the proven docker-prep.sh tarball approach. This commit documents the lessons learned and future considerations. Generated with [Devin](https://cli.devin.ai/docs) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- docs/DOCKER_DEPLOYMENT_GUIDE.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/docs/DOCKER_DEPLOYMENT_GUIDE.md b/docs/DOCKER_DEPLOYMENT_GUIDE.md index 8f49501..3d74698 100644 --- a/docs/DOCKER_DEPLOYMENT_GUIDE.md +++ b/docs/DOCKER_DEPLOYMENT_GUIDE.md @@ -12,6 +12,39 @@ This guide documents the shared base image strategy for Docker deployment across all ByteLyst products. This approach minimizes disk space duplication by building a single base image containing all `@bytelyst/*` shared packages, which all product images then inherit from. +**Status: Experimental / Deferred** + +The base image strategy has been implemented and tested, but is currently **deferred** due to workspace complexity issues. All ByteLyst products (notes, clock, trading) currently use the **docker-prep.sh tarball approach**. + +### Why the Base Image Approach Was Deferred + +The base image approach encountered fundamental issues with pnpm workspaces: + +1. **Workspace Structure Mismatch**: The base image sets up a workspace in `/app` with all `@bytelyst/*` packages. Product Dockerfiles try to install in subdirectories like `/app/backend`, which creates workspace context issues. + +2. **pnpm Workspace Requirements**: pnpm workspaces expect all workspace packages to be present and resolvable during installation. When a product tries to `pnpm install` in its subdirectory, it cannot resolve the workspace packages properly. + +3. **Dependency Resolution Complexity**: The product's package.json has workspace protocol dependencies (e.g., `workspace:*` or `workspace:^`). These resolve correctly in the common plat repo but fail when the product is built in isolation using the base image. + +4. **Build Tool Availability**: The base image would need to include all build tools (TypeScript, Next.js, etc.) globally, which increases complexity and image size. + +### Current Approach: docker-prep.sh + +All products currently use the **docker-prep.sh tarball approach**: +- `docker-prep.sh` builds all `@bytelyst/*` packages and packs them into tarballs +- Dockerfiles copy these tarballs and extract them during build +- This approach is slower (~2-3 min) but reliable and works with the current workspace structure + +### Future Considerations + +The base image approach could be revisited if: +1. The workspace structure is simplified (e.g., move to a monorepo or use a different package manager) +2. pnpm adds better support for cross-repo workspace inheritance +3. A custom npm registry is set up to publish `@bytelyst/*` packages +4. The build process is restructured to not rely on workspace protocols + +For now, the docker-prep.sh approach is recommended for all ByteLyst products. + ### Problem Statement **Without shared base images:**