document/content/docs/self-host/migration/docker_mongo.en.mdx
Related PR -- open this to discuss with the author
How to use mongodump to migrate FastGPT's MongoDB from Environment A to Environment B.
Prerequisites:
docker exec -it mongo sh
mongo -u 'username' -p 'password'
>> show dbs
Confirm you can see the fastgpt database and note the database name for export.
Create a temporary directory for import/export on both the container and the host, e.g., data/backup [Environment A + Environment C].
Enter the FastGPT Docker container:
docker exec -it fastgpt sh
mkdir -p /data/backup
Once created, exported MongoDB data will appear in the data/backup directory under your local FastGPT installation folder (auto-synced via volume mount). If it doesn't sync automatically, you can manually create the directory and use docker cp to copy files out (this rarely happens).
Navigate to the FastGPT directory, go into the mongo folder, and create a backup subdirectory:
mkdir -p /fastgpt/data/backup
Also create a directory in the new [Environment B]:
mkdir -p /fastgpt/mongobackup
###2. Export Data from [Environment A] Enter Environment A and use mongodump to export the MongoDB database.
Run mongodump to export data files to the temporary directory (data/backup).
[The export path is set to /data/backup in the command. Since the FastGPT config already has data persistence set up, the exported files will sync to the host's fastgpt/mongo/data/backup directory.]
Single command to export (run on the host, no need to enter the container):
docker exec -it mongo bash -c "mongodump --db fastgpt -u 'username' -p 'password' --authenticationDatabase admin --out /data/backup"
You can also enter the container and combine directory creation with the export:
1.docker exec -it fastgpt sh
2.mkdir -p /data/backup
3. mongodump --host 127.0.0.1:27017 --db fastgpt -u "username" -p "password" --authenticationDatabase admin --out /data/backup
docker cp mongo:/data/backup [local-fastgpt-dir]:/fastgpt/data/backup>
2.2 For beginners, it's recommended to compress the directory and download it to your local staging environment [A -> C] for verification. This ensures you have a backup and can check file counts. Experienced users can transfer directly to the new server [A -> B].
2.2.1 Navigate to the [Environment A] source system's local fastgpt/mongo/data directory:
cd /usr/fastgpt/mongo/data
Compress the files:
tar -czvf ../fastgpt-mongo-backup-$(date +%Y-%m-%d).tar.gz ./
Download the archive to your local machine [A -> C] for verification. Experienced users can sync directly to Environment B's fastgpt data directory.
scp -i /Users/path/[your-pem-file] root@[cloud-server-ip]:/usr/fastgpt/mongo/fastgptbackup-2024-05-03.tar.gz /[local-path]/Downloads/fastgpt
Experienced users can transfer directly to the new environment:
scp -i /Users/path/[your-pem-file] root@[old-server-ip]:/usr/fastgpt/mongo/fastgptbackup-2024-05-03.tar.gz root@[new-server-ip]:/Downloads/fastgpt2
2.2 [Environment C] Verify the archive is complete. If not, re-export. Cross-environment scp transfers can occasionally lose data.
After downloading the archive to Environment C, extract it to a custom directory, e.g., user/fastgpt/mongobackup/data:
tar -xvzf fastgptbackup-2024-05-03.tar.gz -C user/fastgpt/mongobackup/data
The extracted files should be .bson files. Verify the file count matches the source. If they don't match, the new FastGPT environment will have no data after import.
If everything looks good, upload the archive to Environment B's designated directory (e.g., /fastgpt/mongobackup). Do not place it in fastgpt/data/ -- that directory will be cleared later, and having extra files there will cause import errors.
scp -rfv [local-path]/Downloads/fastgpt/fastgptbackup-2024-05-03.tar.gz root@[new-server-ip]:/Downloads/fastgpt/backup
tar -xvzf fastgptbackup-2024-05-03.tar.gz -C user/fastgpt/mongobackup/data
Verify the file count again against your earlier check.
Experienced users can use tar to verify archive integrity. The above steps are for beginners to facilitate comparison.
Since the files aren't in the data/ directory, they won't auto-sync into the container. Also ensure the container's data directory is clean, or the import will fail.
docker cp user/fastgpt/mongobackup/data mongo:/tmp/backup
If the mongo/db directory isn't freshly initialized, mongorestore may fail. If you encounter errors, try initializing mongo.
Commands:
cd /fastgpt-install-dir/mongo/data
rm -rf *
docker exec -it mongo mongorestore -u "username" -p "password" --authenticationDatabase admin /tmp/backup/ --db fastgpt
Note: if the imported file count seems too low, the import likely failed. A failed import means you can log in to FastGPT but see no data.
docker compose restart
docker logs -f mongo # Strongly recommended: check mongo logs before logging in. If mongo has errors, the web UI will also show errors.
If mongo starts normally, you should see output like this (not "mongo is restarting" -- that indicates an error):
Error state: