d25c21d781
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>
139 lines
4.5 KiB
Markdown
139 lines
4.5 KiB
Markdown
# 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.
|