Container Base Image Research
1. Alpine vs Debian-slim Image Comparison
R1, R2: Related Requirements
1.1 Finding
Alpine uses musl libc; Debian-slim uses glibc. Most npm pre-built binaries target glibc. Image size difference is ~80MB compressed, ~200MB uncompressed. Debian-slim includes bash by default.
1.2 Options
| Aspect | Alpine (musl) | Debian-slim (glibc) |
|---|---|---|
| Compressed size | ~180MB | ~260MB |
| Uncompressed size | ~500MB | ~700MB |
| Native npm packages | Often fail, require musl-specific builds | Work out of the box |
| Pre-built binaries (Linux-x64-glibc) | Incompatible | Compatible |
| MCP servers with native deps | May fail silently or at runtime | Expected to work |
| Python C extensions | May require musl-specific compilation | Work with standard gcc |
| bash | Not included (ash only) | Included |
1.3 Recommendation
Switch to Debian-slim. The compatibility benefits outweigh the ~80MB size increase. Alpine’s musl libc is a constant source of friction, and the “Before You Install” workarounds exist solely because of it.
1.4 Decision
Selected: Switch to Debian-slim
Decided by: erik@uvilo.com — 2026-04-15
2. LibreChat-Specific Compatibility
R1, R3, R5: Related Requirements
2.1 Finding
LibreChat’s official Dockerfile supports both Alpine and Debian variants. All current MCP servers (vercel-mcp, playwright, composio, etc.) are pure JS/TS that should work on either base. Playwright requires browser binaries with different deps on Debian. Forge Python scripts (MongoDB, Typesense, agent management) benefit from glibc. Railway builds from Dockerfile automatically.
2.2 Options
| Concern | Risk Level | Mitigation |
|---|---|---|
| Larger image size | Low | ~80MB increase is acceptable per R2 |
| Playwright browser deps missing | Medium | Install via npx playwright install --with-deps chromium |
| LibreChat compatibility | Low | Test thoroughly before deploying |
| Python package incompatibility | Very Low | glibc packages should work fine |
2.3 Recommendation
Proceed with migration. All risks have clear mitigations and the compatibility benefits are significant.
2.4 Decision
Selected: Proceed with migration
Decided by: erik@uvilo.com — 2026-04-15
3. Standard Tooling Availability
R3: Related Requirement
3.1 Finding
Debian-slim includes bash by default. Other standard tools install via apt-get.
3.2 Options
| Tool | Alpine (apk add) | Debian-slim (apt-get install) |
|---|---|---|
| bash | Not included | Included |
| curl | apk add curl | apt-get install curl |
| wget | apk add wget | apt-get install wget |
| nano | apk add nano | apt-get install nano |
| git | apk add git | apt-get install git |
| python3 | apk add python3 | apt-get install python3 |
| gcc/build-essential | apk add build-base | apt-get install build-essential |
3.3 Recommendation
Debian-slim meets R3 — bash included, others easily installable.
3.4 Decision
Selected: Debian-slim meets tooling requirements
Decided by: erik@uvilo.com — 2026-04-15
4. Migration Path
R4: Related Requirement
4.1 Finding
The migration requires: building a test image, installing system packages, testing MCP servers/npm packages, testing Forge Python scripts, verifying LibreChat, comparing image size, then updating Dockerfile and deploying.
4.2 Recommendation
Follow the step-by-step migration path documented above, testing each layer before proceeding.
4.3 Decision
Selected: Follow step-by-step migration
5. Parallel Deployment Strategy
R6: Related Requirement
5.1 Finding
To validate the new Debian-slim build with real data before cutover, both the Alpine (current) and Debian-slim (new) builds must run simultaneously. This is a temporary dual-deployment, not a permanent HA setup. The cutover is a one-time event: verify the new build, flip the DNS, tear down the old one.
5.2 Required Components
| Component | Details |
|---|---|
| Separate URL | New build needs its own hostname (e.g., librechat-new.uvilo.ai) for testing before cutover. After verification, librechat.uvilo.ai DNS is pointed to the new build. |
| Repo checkout | New build must git clone or git pull /workspace/erik/uvilo-os during startup so Forge scripts, MCP configs, and agent instructions are available. |
| MongoDB sync | The new build’s MongoDB instance must be seeded with the current production data. Options: (1) mongodump/mongorestore from the existing instance, (2) point both builds at the same MongoDB instance during the parallel run. |
| Typesense index | The search index must be available on the new build. Options: (1) re-index from scratch (slow but simple), (2) export/import the Typesense snapshot, (3) point both builds at the same Typesense instance during the parallel run. |
| Cutover | Once the new build is verified end-to-end (MCP servers, Forge scripts, chat, search), update the librechat.uvilo.ai DNS to point to the new build, then decommission the old Alpine build. |
5.3 Options for Data Sharing
| Approach | Pros | Cons |
|---|---|---|
| Shared MongoDB instance | Zero data sync needed; both builds see live data | Single point of failure during migration; connection limit concerns |
| MongoDB dump/restore | Clean separation; each build has its own data | Data drift during parallel run; must re-sync before cutover |
| Shared Typesense instance | No re-indexing needed | Network latency if instances are in different regions |
| Re-index from scratch | Self-contained; validates the indexing pipeline | Slow (depends on corpus size); uses compute on new build |
| Typesense snapshot | Fast; preserves index state | Snapshot may be stale if index changes during parallel run |
5.4 Recommendation
Use shared instances for both MongoDB and Typesense during the parallel run. This eliminates data sync/drift problems and is simpler. The shared-instances approach is temporary — after cutover, the new build uses its own dedicated instances.
Migration sequence:
- Deploy new Debian-slim build on Railway with separate URL
- Configure it to use the existing MongoDB and Typesense instances
- Verify all functionality end-to-end via the new URL
- Migrate MongoDB and Typesense to the new build’s dedicated instances (if desired)
- Flip
librechat.uvilo.aiDNS to the new build - Decommission the old Alpine build
5.5 Decision
Selected: Shared instances during parallel run
Shared MongoDB and Typesense instances during parallel run. Migrate to dedicated instances before DNS cutover (not after).
Decided by: erik@uvilo.com — 2026-05-14