librechat-analytics/docs/MIGRATION.md

Migrate LibreChat from /home/michael_clervi/ to /opt/LibreChat

Why

LibreChat on optical-librechat-dev is installed under a user's home directory (/home/michael_clervi/LibreChat). That user account is being deactivated. Moving to /opt/LibreChat decouples the install from any user account.

Data Locations

Before migrating, know where all your data lives:

Data	Volume Type	Location	Notes
MongoDB (users, chats, transactions, costs)	Bind mount	./data-node/	The most critical data
Images	Bind mount	./images/	User-uploaded images
Uploads	Bind mount	./uploads/	File attachments
Logs	Bind mount	./logs/	API logs
Meilisearch index	Bind mount	./meili_data_v1.12/	Search index (can be rebuilt)
Config files	Bind mount	./librechat.yaml, ./.env	LibreChat configuration
Nginx config	Bind mount	./client/nginx.conf	Web server config
SSL certs	Absolute path	/etc/cert/	Not in LibreChat dir — unaffected
VectorDB (pgvector)	Named volume	pgdata2	Docker-managed — unaffected

All bind-mount data uses relative paths (./) in deploy-compose.yml, so everything is inside the LibreChat directory. A single cp -a captures it all.

Migration Steps

All commands as root on the server.

Step 1: Stop all containers

cd /home/michael_clervi/LibreChat
docker compose -f deploy-compose.yml down

Wait for all containers to stop. This prevents data corruption during the copy.

Step 2: Copy to /opt (preserve permissions)

cp -a /home/michael_clervi/LibreChat /opt/LibreChat

This copies everything including MongoDB data, images, uploads, configs, and logs. The -a flag preserves file permissions and ownership.

Important: We use cp (not mv) so the original stays as a rollback option.

Step 3: Start from new location

cd /opt/LibreChat
docker compose -f deploy-compose.yml up -d

No config file changes are needed — all volume mounts in deploy-compose.yml use relative paths (./data-node, ./images, etc.).

Step 4: Verify everything works

Check each of these:

• LibreChat loads at https://chat-dev.oliver.solutions
• You can log in (MongoDB users are intact)
• Chat history is visible (MongoDB data intact)
• Images load in old conversations
• File uploads are accessible
• Search works (Meilisearch data intact)
• Code interpreter works (test in a conversation)
• Analytics dashboard loads at /librechat-analytics/
• Admin dashboard loads at /admin-dashboard/

Step 5: Update backup script

Edit /opt/Librechat-backups/librechat-backup.sh:

# Change:
LIBRECHAT_DIR="/home/michael_clervi/LibreChat"
# To:
LIBRECHAT_DIR="/opt/LibreChat"

If the script also references LibreCodeInterpreter under michael_clervi, update that path too.

Step 6: Move LibreCodeInterpreter (if present)

# Check if it exists at the old location
ls /home/michael_clervi/LibreCodeInterpreter

# If yes, copy it:
cp -a /home/michael_clervi/LibreCodeInterpreter /opt/LibreCodeInterpreter

Step 7: Clean up old location

Only after you've verified everything in Step 4:

rm -rf /home/michael_clervi/LibreChat
rm -rf /home/michael_clervi/LibreCodeInterpreter

What Does NOT Need Changing

File	Why
deploy-compose.yml	All volume paths are relative (./)
.env	No hardcoded directory paths
client/nginx.conf	References Docker container names, not file paths
SSL certs	Stored at /etc/cert/, outside LibreChat directory
VectorDB	Uses Docker named volume pgdata2, not tied to directory
Analytics dashboard	Already at /opt/librechat-analytics/

Rollback

If anything goes wrong after Step 3:

# Stop the new instance
cd /opt/LibreChat
docker compose -f deploy-compose.yml down

# Start from the original location
cd /home/michael_clervi/LibreChat
docker compose -f deploy-compose.yml up -d

The original directory is untouched until you explicitly delete it in Step 7.

Expected Downtime

2-3 minutes total:

• Stop containers: ~15 seconds
• Copy data: ~1 minute (depends on data size)
• Start containers: ~30-60 seconds

Applying to Other Servers

The same process works for any server where LibreChat is under a user's home directory. Just replace the source path. Verify the deploy-compose.yml on that server also uses relative paths before proceeding.