Container Base Image Requirements

---

Problem

The current LibreChat deployment uses node:20-alpine as its base image. Alpine Linux uses musl libc instead of glibc, which causes compatibility issues with many npm packages and MCP servers. This has led to:

1. Installation failures — packages requiring native compilation (e.g., better-sqlite3, canvas) fail on musl
2. Missing standard tools — no curl, wget, nano, bash out of the box; each must be installed via apk add
3. Shell differences — Alpine uses ash (BusyBox), not bash, causing script compatibility issues
4. Workaround overhead — the “Before You Install” section in Forge_Infrastructure.md exists solely because of Alpine constraints

---

Requirements

R1: Base image compatibility

All current MCP servers and npm packages must work without musl-specific workarounds on the new base image.

R2: Acceptable image size

Image size increase must be under 200MB (uncompressed) compared to the Alpine base.

R3: Standard tooling available

Standard Linux tools (curl, wget, nano, bash) must be available or easily installable.

R4: Tested migration path

The migration must be documented and tested end-to-end before deploying to production.

R5: No regressions

No regression in existing LibreChat functionality, MCP server operation, or Forge scripts.

R6: Parallel deployment — both builds must run simultaneously

The new Debian-slim build and the current Alpine build must run at the same time during migration. This enables live validation of the new build against real data before cutting over traffic. The old build stays up until the new one is confirmed working end-to-end.

Implications:

• The new build needs its own URL (e.g., librechat-new.uvilo.ai) for testing before cutover
• The new build must check out /workspace/erik/uvilo-os so Forge scripts and configs are available
• MongoDB data must be synced to the new build’s instance
• Typesense index must be transferred or rebuilt on the new build
• Once the new build is verified, https://librechat.uvilo.ai is pointed to the new build and the old build is decommissioned

Success Criteria

#	Criterion	Measured by
V1	All MCP servers and npm packages work on Debian-slim	Successful startup and execution of each server
V2	Image size increase < 200MB uncompressed	docker images comparison
V3	Standard tools available	which curl wget nano bash passes in container
V4	Migration path documented and tested	Step-by-step guide verified by a test deploy
V5	No regression in existing functionality	All features work as before after deployment
V6	Both builds run simultaneously; new build accessible at separate URL	New build reachable at its URL with full data and Forge config

---

Out Of Scope

• Changing the LibreChat application code itself
• Switching container orchestration platforms
• Optimizing image size beyond the base image swap
• Multi-architecture builds
• Maintaining long-term dual-build infrastructure (parallel run is temporary, ended by cutover)