docs: Add migration guide for moving LibreChat install to /opt
Step-by-step guide for relocating LibreChat from a user's home directory to /opt/LibreChat, with data location mapping and rollback instructions. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
DJP
parent
80a7e0ecee
commit
d25c21d781
1 changed files with 139 additions and 0 deletions
139
docs/MIGRATION.md
Normal file
139
docs/MIGRATION.md
Normal file
|
|
@ -0,0 +1,139 @@
|
|||
# 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
|
||||
|
||||
```bash
|
||||
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)
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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`:
|
||||
|
||||
```bash
|
||||
# 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)
|
||||
|
||||
```bash
|
||||
# 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:**
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
# 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.
|
||||
Loading…
Add table
Reference in a new issue