Back Up Your AI Workspace and Restore It

What you will build

A recovery set for a disposable LibreChat workspace, then a restore into an independent Compose project. You will verify accounts, conversation content, and file references instead of calling an untested archive a backup.

This guide covers a deliberately small recovery exercise. A production stack with notes in another database, scheduled agents, vector indexes, or external object storage needs additional captures. Allow 1-2 hours plus transfers and index rebuilding.

Before you start

Complete the LibreChat guide, create a clearly named test conversation, and upload a harmless text file if supported. Prepare a private backup directory outside the repository and a separate restore location.

Record git rev-parse HEAD, image IDs, Compose project name, required encryption secrets, and mount locations. Inspect mounts locally; do not publish full inspection output or resolved Compose configuration because either can expose secrets.

Decide whether one hour of lost work is acceptable and how long restoration may take. These are your recovery point and recovery time objectives.

1. Map every piece of state

For this exercise, capture MongoDB, upload and image bind mounts, .env, librechat.yaml, Compose configuration, and local code patches. Record search and vector services separately. Source documents are authoritative; their indexes may be rebuildable only through the installed application's documented process.

If an application saves Notes through a separate service, backing up MongoDB alone will not capture those notes. Follow the actual write path.

2. Pause writes and export MongoDB

Run from the source checkout. Replace the example backup path with a private directory that already exists and has sufficient space:

umask 077
BACKUP="$HOME/ai-recovery-set"
test -d "$BACKUP" || exit 1
docker compose stop api rag_api
docker compose exec -T mongodb mongodump --archive --gzip > "$BACKUP/mongodb.archive.gz"
test -s "$BACKUP/mongodb.archive.gz" || exit 1

Use service names from your Compose file; stop only its actual writers. The default local MongoDB lab may not require credentials. If yours does, use its supported protected credential mechanism rather than putting passwords in command history.

Check the export's exit status. A file that exists after a failed redirect is not necessarily a valid dump.

3. Capture matching files and configuration

With writes still paused, copy the relevant bind-mounted directories and protected configuration into the recovery directory. For the default source checkout, inspect whether uploads and images are the actual mounts before using this example:

tar -czf "$BACKUP/files-and-config.tar.gz" \
  .env librechat.yaml docker-compose.yml docker-compose.override.yml uploads images
sha256sum "$BACKUP/mongodb.archive.gz" "$BACKUP/files-and-config.tar.gz" > "$BACKUP/SHA256SUMS"
docker compose start api rag_api

If a listed path does not exist or a mount points elsewhere, adapt the capture explicitly and verify the archive's contents. Do not suppress archive errors. Include your changes and required external services in a written manifest.

Encrypt the recovery set before copying it off the machine. Store decryption material separately, and keep a copy that the application cannot overwrite. Do not put the recovery set in the public web root.

4. Prepare an isolated restore

Use the same source commit and compatible image versions in a new directory. Disable outbound mail, webhooks, scheduled tasks, and external tool access. The exercise's Ollama service is local; do not point restored agents at production credentials.

Extract the archive into the new checkout only after checking its member names. Preserve the original encryption secrets for restored credentials, but restrict who can read them.

Create a final restore.override.yml that changes the API host port:

services:
  api:
    ports: !override
      - "127.0.0.1:3081:3080"

Check for explicit container_name and volume name settings in the copied files. A different Compose project name does not isolate resources with globally fixed names. Remove or rename those collisions before startup; leave the source deployment untouched.

5. Restore and verify

Use the independent project name and the full configuration list consistently:

docker compose -p ai-restore -f docker-compose.yml -f docker-compose.override.yml -f restore.override.yml up -d mongodb
docker compose -p ai-restore -f docker-compose.yml -f docker-compose.override.yml -f restore.override.yml exec -T mongodb mongorestore --archive --gzip < "$BACKUP/mongodb.archive.gz"
docker compose -p ai-restore -f docker-compose.yml -f docker-compose.override.yml -f restore.override.yml up -d

Restore only into a confirmed empty target. Start additional services after restoring their supported backups or following documented index-rebuild procedures. Do not use destructive restore flags against a source database.

Open port 3081. Verify the test account, conversation text, upload download, a new chat, and user separation. Search failure is a recovery failure to investigate, not something to hide because the chat page loads. Record elapsed recovery time and all missing components.

When it breaks and how to stop

Unreadable saved credentials often indicate missing encryption secrets. Missing uploads usually indicate mismatched mount paths or ownership. A port or container-name collision means isolation is incomplete; stop the restore project rather than the source.

Stop the restore with the same project and file arguments followed by stop. Keep the recovery set until the exercise is reviewed. Remove only explicitly identified disposable resources after confirming none belong to production.

Explore theLAB