bytelyst/learning_ai_invt_trdg
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(docker): document base image approach as deferred due to workspace complexity

Browse Source 
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>
This commit is contained in:
root 2026-05-09 23:35:50 +00:00
parent 5d9755fc0a
commit 34ed7813ee
1 changed files with 33 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
docs/DOCKER_DEPLOYMENT_GUIDE.md
View File

@ -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. 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 ### Problem Statement
**Without shared base images:** **Without shared base images:**