Open
Conversation
- Add Node.js/nvm installation with version checking - Add Docker installation for Ubuntu and Rocky Linux - Add GitHub CLI installation - Add MongoDB container setup with authentication - Implement idempotency checks for all components - Add user prompts for upgrades and configuration
- Add environment configuration with .env file generation - Implement JWT secret generation (openssl or fallback) - Add MongoDB URI configuration - Add npm dependency installation with idempotency - Add package build process (data-provider, api, client) - Interactive prompts for existing configs - Backup creation for existing .env files
- Add select_deployment_mode() with interactive menu - Implement setup_native_mode() for npm-based development - Implement setup_docker_compose_mode() for container setup - Three options: Native (recommended), Docker Compose, or Both - Native mode: MongoDB in Docker, app via npm with HMR - Docker Compose mode: All services containerized - Graceful handling of missing docker-compose.dev.yml - Conflict detection for standalone MongoDB container - Clear usage instructions for each deployment mode - Integrated into main() function flow - Added test-phase4.sh validation script
- Add verify_setup() for comprehensive system checks * Node.js v20+ version verification * npm, Docker, Docker Compose availability * MongoDB container status and connectivity test * .env file validation with critical variables check * Dependencies and package builds verification * Clear pass/fail reporting with actionable error messages - Add test_application() for optional startup test * Interactive opt-in (defaults to skip) * Runs 'npm run dev' in foreground * User can observe startup and press Ctrl+C * Helpful error messages for common issues - Add comprehensive completion message * Next steps for Native and Docker Compose modes * Quick reference commands * Troubleshooting tips * Documentation links - Mark Phase 4 complete in implementation plan - Add test-phase5.sh validation script - Script now 1,439 lines (+235 lines)
- Create dev-setup/ directory for better organization - Move setup-dev-env.sh to dev-setup/ - Move SETUP_SCRIPT_IMPLEMENTATION_PLAN.md to dev-setup/ - Move all test scripts (test-phase*.sh) to dev-setup/ - Prepares for additional Phase 6 test files
Interactive Testing:
- Add interactive-test-ubuntu.sh for manual Ubuntu testing
- Add interactive-test-rocky.sh for manual Rocky Linux testing
- Mounts local LibreChat code into container
- Drops into interactive shell for observation
- Simulates VDI environment with non-root user
Automated Testing:
- Add test-docker-ubuntu.sh for CI Ubuntu testing
- Add test-docker-rocky.sh for CI Rocky Linux testing
- Add Dockerfile.test-ubuntu for Ubuntu test image
- Add Dockerfile.test-rocky for Rocky test image
- Runs setup script non-interactively
- Reports success/failure for CI integration
Script Enhancements:
- Add IS_AUTOMATED flag for CI/test environments
- Update prompt_yes_no() to auto-accept defaults in automated mode
- Update select_deployment_mode() to skip prompts in automated mode
- Add CI and AUTOMATED_TEST environment variable support
- Maintain full interactivity for normal usage
Documentation:
- Add comprehensive dev-setup/README.md
- Usage instructions for all testing modes
- Troubleshooting guide
- CI/CD integration examples
- File structure documentation
Testing modes now available:
1. Manual: ./setup-dev-env.sh (normal interactive usage)
2. Interactive test: ./interactive-test-{ubuntu,rocky}.sh
3. Automated test: ./test-docker-{ubuntu,rocky}.sh
4. Unit tests: ./test-phase*.sh
- Add SCRIPT_DIR detection to find script location - Detect when script is in dev-setup/ subdirectory - Automatically change to LibreChat root directory - Set LIBRECHAT_ROOT variable for future path references - Resolves package.json not found error when running from dev-setup/ Now works correctly from any location: cd dev-setup && ./setup-dev-env.sh ✓ ./dev-setup/setup-dev-env.sh ✓ cd /anywhere && /path/to/dev-setup/setup-dev-env.sh ✓
Issue #1 - Docker command errors during detection: - Add check_command docker before running docker ps - Suppress stderr with 2>/dev/null for cleaner output - Prevents 'docker: command not found' during environment detection - MongoDB detection gracefully reports 'not found' when docker missing Issue #2 - SSL certificate verification failures: - Add update-ca-certificates to Ubuntu Dockerfile - Add update-ca-trust to Rocky Linux Dockerfile - Update interactive test scripts to refresh CA certificates - Fixes 'curl: (60) SSL certificate problem' errors - Ensures HTTPS connections work properly in containers Both interactive and automated testing now handle these edge cases cleanly.
- Mount /usr/local/share/ca-certificates from VDI into containers - Ubuntu: Update ca-certificates to include mounted certs - Rocky: Copy certs to /etc/pki/ca-trust/source/anchors/ and update trust - Resolves SSL certificate issues behind corporate proxy/SSL inspection - Certificates are managed by Paychex on VDIs and now shared with containers This allows test containers to make HTTPS requests (curl, nvm install, etc.) through Paychex corporate network with SSL inspection.
- Temporarily disable set -u when sourcing nvm.sh - nvm.sh has unset variables that conflict with our strict mode - Wrap nvm sourcing with set +u / set -u to allow it to load - Re-enable strict mode after nvm is sourced - Fixes: 'PROVIDED_VERSION: unbound variable' error This allows nvm to work properly while maintaining strict error checking in the rest of our script.
- Wrap nvm installer script execution (curl | bash) - Wrap all nvm install/use/alias commands - nvm.sh contains unset variables that conflict with set -u - Previous fix only wrapped sourcing, but installer also triggers nvm.sh - Now disables -u flag before ANY nvm operation, re-enables after Fixes: 'PROVIDED_VERSION: unbound variable' error during nvm installation
- Skip 'newgrp docker' prompt in container environments * Docker group changes don't take effect in same container session * Avoids script restart loop in container testing - Skip interactive prompt in automated mode * CI/CD environments should not prompt - Change default from 'y' to 'n' for group switch prompt * Less disruptive for users on real VDIs * User can manually run newgrp if needed - Fix exec command to use absolute path * Use readlink -f to resolve full path to script * Prevents 'sh: 1: ./setup-dev-env.sh: not found' error * sg/newgrp executes in different context, relative paths fail - Add continuation message when user declines group switch * Docker commands may require sudo until next login Resolves: Script termination with 'not found' error during group switching
- LibreChat uses standard docker-compose.yml, not dev-specific variant - Update setup_docker_compose_mode() to check for docker-compose.yml - Remove -f docker-compose.dev.yml from all docker compose commands - Use simple 'docker compose' commands (v2 plugin auto-detects compose file) Resolves: docker-compose.dev.yml not found error
- Create docker-compose.override.yml for VDI environments * MongoDB 4.4.18 for CPUs without AVX support * Run containers as root (user: 0:0) to avoid permission issues * Mount paychex-root.pem certificate for SSL inspection * Mount librechat.yaml configuration - Add comprehensive .env warnings for Paychex-specific config * Azure OpenAI endpoint configuration * SSL certificate paths for corporate proxy * RAG configuration with Azure embeddings * OpenID/SSO configuration guidance - Integrate docker-compose override setup into Phase 3 - Provide clear guidance on what developers need to configure - Backup existing files before regeneration Addresses: VDI environments without AVX, corporate SSL inspection, Paychex-internal service endpoints
- Remove output suppression (> /dev/null 2>&1) to see if install fails - Remove -q flag for verbose output - Helps debug sudo installation issues in container
Multiple SSL-related fixes for Rocky Linux 9 containers: 1. Bootstrap phase: - Temporarily disable dnf SSL verification for initial package install - Use --allowerasing flag to handle curl-minimal conflict - Properly update CA trust after ca-certificates installation 2. nvm installation: - Disable git SSL verification temporarily for nvm clone - Use curl -k flag for downloading nvm installer - Use HTTP mirror (http://nodejs.org/dist) for Node.js downloads - Install specific Node v20 instead of --lts (avoids SSL lookup) 3. Package manager improvements: - Detect sudo availability before using it - Use eval for proper multi-word command expansion - Add --allowerasing for Rocky/RHEL package conflicts Resolves multiple issues: - SSL certificate problem: unable to get local issuer certificate - sudo: command not found - curl-minimal vs curl conflict - nvm install --lts network lookup failures Tested: Node.js v20.20.0 installs successfully in Rocky 9 container
- Detect SSL certificate issues before Docker install - Use curl -k to download docker-ce.repo manually in containers - Apply --setopt=sslverify=false for dnf operations when needed - Fallback to normal dnf config-manager in real VDI environments This allows Docker installation to proceed in Rocky containers that lack proper SSL certificate trust, while maintaining security in real VDI environments where SSL works correctly.
Remove all SSL bypass workarounds from setup-dev-env.sh. The proper solution is to mount Paychex CA certificates into containers, not to disable SSL verification. Changes: 1. Removed HTTP mirror workarounds for Node.js downloads 2. Removed curl -k and git SSL bypass for nvm installation 3. Removed Docker dnf SSL disable flags 4. Restored normal --lts flag for nvm install 5. Added build artifact cleanup with permission fix The interactive-test-rocky.sh script already properly mounts certificates from /usr/local/share/ca-certificates which is the correct approach for VDI environments. Certificate mounting (already in test scripts): -v /usr/local/share/ca-certificates:/usr/local/share/ca-certificates:ro Then copied to Rocky location: cp /usr/local/share/ca-certificates/*.crt /etc/pki/ca-trust/source/anchors/ update-ca-trust This ensures SSL works properly while maintaining security.
- Add **/undefined/ to .gitignore for rollup typescript plugin cache - Fix cleanup paths: api/dist -> packages/api/dist, client/dist -> packages/client/dist - Fix nvm alias syntax: use 'lts/*' instead of --lts flag - Prevents test containers from polluting repo with build cache files
paychex-gcarlson
force-pushed
the
feature/AIA-1974_dev-env-script-rebased
branch
from
d51f89a to
fb0fb84
Compare
- Remove all Paychex-internal URLs from configuration examples - Replace with placeholders directing to internal documentation - Also fix NODE_EXTRA_CA_CERTS path (remove extra slash)
…where logs mount path was incorrect.
…e onboarding dev needs to fill out. randomly generate the CREDS config. Update the script to make it clearer what the difference between the two run modes are.
|
New Issues (395)Checkmarx found the following issues in this Pull Request
|
paychex-joser
approved these changes
Feb 11, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
LibreChat VDI Development Environment Setup Script
Overview
This PR introduces an automated setup script for LibreChat local development on Paychex VDIs (Ubuntu and Rocky Linux), along with a complete Docker-based testing framework. The script handles all aspects of environment setup including security-compliant configuration management, VDI-specific optimizations, and robust error handling.
Key Features
🔒 Security & Compliance
Protected Internal Infrastructure:
docker-daemon.json.examplecommitted with placeholder URLs (<your-registry-N.example.com>)docker-daemon.json.local(git-ignored) holds actual registry URLs🖥️ Paychex VDI Optimizations
Docker Home Relocation:
/var/lib/dockerto/home/docker/varpartition on VDI systemsMongoDB 4.4 Compatibility:
mongoshell (notmongoshwhich requires MongoDB 5.0+)Certificate Handling:
paychex-root.pemfor corporate SSL inspection🚀 Developer Experience
Interactive Guidance:
Idempotent & Resilient:
Flexible Deployment Modes:
🧪 Testing Framework
Docker-based Validation:
Test Script Options:
Files Added/Modified
Core Setup Script
dev-setup/setup-dev-env.sh(2,438 lines)Configuration Management
docker-daemon.json.example- Public template with placeholder registry URLs.gitignore- Added patterns for git-ignored files:docker-daemon.json.local(user's actual registry config)*.bak,*.backup,*docker-compose-override*.bak*)Documentation
dev-setup/README.md- Comprehensive setup guide including:Testing Framework
Test Runners:
test-docker-ubuntu.sh- Non-interactive Ubuntu validation (CI-ready)test-docker-rocky.sh- Non-interactive Rocky Linux validation (CI-ready)interactive-test-ubuntu.sh- Interactive Ubuntu test environmentinteractive-test-rocky.sh- Interactive Rocky test environmentContainer Definitions:
Dockerfile.test-ubuntu- Ubuntu 24.04 test container with LibreChat prerequisitesDockerfile.test-rocky- Rocky Linux 9 test container with enterprise Linux setupRun Scripts (Previously Created)
run-backend.sh- Start LibreChat API server (native mode)run-frontend.sh- Start React dev server with HMR (native mode)run-docker.sh- Start all services via Docker ComposeEnvironment Variables for Testing/CI
CI=true- Non-interactive mode, uses defaultsAUTOMATED_TEST=true- Skips Docker-dependent tests (for basic containers)TEST_MODE=1- Bypasses LibreChat repository detectionInstalled by Script:
Review Focus Areas
Testing Checklist for Reviewers: