Migrate from Cloud-Hosted to Self-Managed Workspace

If you're planning to move from a cloud-hosted Rocket.Chat workspace to a self-managed workspace, this guide will walk you through the required steps. Migrating your workspace involves transferring your data (including messages, channels, and uploaded files) to the new infrastructure. This ensures your workspace continues to function seamlessly with all historical data intact in a self-managed environment.

Before you begin

Before starting the migration, make sure you have everything you need. Here's a quick checklist to get ready:

Request your data export: Contact Rocket.Chat support to request a MongoDB export of your cloud-hosted workspace. This export includes your workspace’s messages, users, channels, and all associated metadata. If your export was delivered in multiple parts, refer to Extracting Multi-Part Data Exports to combine them into a single file before proceeding.
Set up a self-managed workspace: If you haven’t already, deploy a new workspace using our Deploy with Docker & Docker Compose guide.
Prepare an Amazon S3 bucket: You’ll use Amazon S3 to store your uploaded assets (files and avatars). Create a new S3 bucket and keep the bucket name handy. We’ll configure Rocket.Chat to read from this bucket after migration. Refer to the Amazon S3 official documentation for more details.

Step 1: Unpack your data

Run the following command to unpack your export:

cat export.tar.gz.* | tar tzvf -
cat export.tar.gz.* | tar xzvf -

This will extract two main folders:

database/: contains a single subfolder (e.g. 68224d495816f19310604d9b/) with your MongoDB data.
files/: contains uploaded assets like avatars and file uploads.

Make sure both folders were created successfully before continuing.

You’ll use the name of the subfolder inside database/ (e.g. 68224d495816f19310604d9b) in later steps. We’ll refer to it as <database-folder> throughout this guide.

Step 2: Transfer your database

Now that you’ve unpacked your export, the next step is to move your MongoDB data into the self-managed Rocket.Chat workspace.

The exported data is located in database/<database-folder>. You’ll copy the <database-folder> into your MongoDB container, then use mongorestore to import the data.

Run the command below to copy the database/ directory contents to the MongoDB container. This will create a /dump directory inside the container with your exported data.
```
docker cp database <mongodb-container-name>:/dump
```
Replace <mongodb-container-name> with your MongoDB container name.
Access the MongoDB container shell by running:
```
docker exec -it <mongodb-container-name> bash
```
Replace <mongodb-container-name> with your MongoDB container name.
In the MongoDB container, navigate to the /dump directory and check that the <database-folder> containing your database is present:
```
cd /dump
ls
```
You should see a folder named something like 68224d495816f19310604d9b which is your <database-folder>.
Run the following command to drop the default rocketchat database and restore the exported data:
```
mongorestore --drop --db rocketchat /dump/<database-folder>
```
Replace <database-folder> with the actual folder name you saw in the previous step (e.g. 68224d495816f19310604d9b).
After the restore process is completed successfully, exit the MongoDB container shell and restart the Rocket.Chat service:
```
docker compose down rocketchat
docker compose up -d rocketchat
```

Your self-managed workspace now has all your previous data.

Step 3: Transfer your files to AWS S3

Rocket.Chat stores uploaded files like user avatars and shared documents in a separate files/ directory from the export. The next step is to organize the files into the correct structure and upload them to your S3 bucket.

Create a subfolder in files/ named after your <database-folder>, then move the avatars and uploads folders into it:
```
mkdir files/<database-folder>
mv files/avatars files/uploads files/<database-folder>/
```
Replace <database-folder> with the actual folder name (e.g. 68224d495816f19310604d9b). This creates the structure Rocket.Chat expects:
```
files/
  └── <database-folder>/
      ├── avatars/
      └── uploads/
```
This step ensures Rocket.Chat can correctly reference these files using the folder name as a namespace.
In your AWS console, upload the entire <database-folder> directory (now containing avatars and uploads) to your S3 bucket. Refer to the official S3 documentation for more details on uploading objects.

Create a new policy in AWS for a user to read and write files to the bucket:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": [
                "s3:GetObject",
                "s3:PutObject",
                "s3:ListBucket",
                "s3:DeleteObject"
            ],
            "Resource": [
                "arn:aws:s3:::<bucket-name>",
                "arn:aws:s3:::<bucket-name>/*"
            ]
        }
    ]
}

Replace <bucket-name> with your actual S3 bucket name.

Create a new IAM user in AWS and attach the policy you created earlier to the user. Generate an access key for the user and copy the Access key and Secret access key.
If you already have a user with an access key, simply attach the policy to that user and proceed.

Step 4: Reconfigure file paths

Now that your files are uploaded to S3, you need to update your Rocket.Chat database so it points to the new file paths. Without this, your workspace won’t be able to find or display previously uploaded files and avatars.

Run this command to access your MongoDB shell and interact with your database:
```
docker exec -i <mongodb-container-name> mongosh
```
Then switch to the Rocket.Chat database:
```
use rocketchat
```
Update the path and URL for all previously uploaded files to match the new structure in your S3 bucket with these commands:
```
db.rocketchat_uploads.updateMany({ "AmazonS3.path": /^<database-folder>/ }, [{ $set: { "AmazonS3.path": { "$concat": ["<database-folder>/uploads/", "$_id"]} } }])

db.rocketchat_uploads.updateMany({ "url": /^https:\/\/<cloud-hosted-workspace-domain>\/ufs\/AmazonS3:Uploads/ }, [{ $set: { "url": { "$concat": ["<your-workspace-url>/ufs/AmazonS3:Uploads/", "$_id", "/", "$name"]} } }])
```
Replace the following appropriately:
1. <database-folder>: the database folder name you extracted earlier (e.g. 68224d495816f19310604d9b)
2. <cloud-hosted-domain>: The previous domain of your cloud-hosted workspace (e.g test.rocket.chat).
3. <your-workspace-url>: The URL for your self-managed workspace where Rocket.Chat is currently running (e.g http://localhost:3000).
Update the path and URL for all previously uploaded avatars to match the new structure in your S3 bucket with these commands:
```
db.rocketchat_avatars.updateMany({ "AmazonS3.path": /^<database-name>/ }, [{ $set: { "AmazonS3.path": { "$concat": ["<database-name>/avatars/", "$_id"]} } }])

db.rocketchat_avatars.updateMany({ "url": /^https:\/\/<cloud-hosted-workspace-domain>\/ufs\/AmazonS3:Avatars/ }, [{ $set: { "url": { "$concat": ["<your-workspace-url>/ufs/AmazonS3:Avatars/", "$_id", "/", "$name"]} } }])
```
Replace the following appropriately:
1. <database-folder>: the database folder name you extracted earlier (e.g. 68224d495816f19310604d9b)
2. <cloud-hosted-domain>: The previous domain of your cloud-hosted workspace (e.g test.rocket.chat).
3. <your-workspace-url>: The URL for your self-managed workspace where Rocket.Chat is currently running (e.g http://localhost:3000).

Exit the MongoDB shell and restart the Rocket.Chat service:

docker compose down rocketchat
docker compose up -d rocketchat

These updates ensure Rocket.Chat loads files from your new S3 location and builds the correct preview URLs. Once this is done, all old file references in your database will point to the correct locations in your new workspace.

Step 5: Access your self-managed workspace

Once the migration is complete, go to your self-managed Rocket.Chat workspace in the browser. Log in using any of your existing user credentials from the previous cloud-hosted workspace. You should be able to view channels, messages, and user data as expected.

At this point, file uploads and avatars may not load properly — that’s expected until you finish the next step below.

Step 6: Configure file storage and workspace URL

To finalize the migration, you need to configure S3 to handle file uploads and set the correct Site URL so files and avatars display correctly in the workspace.

Go to Administration > Workspace > General and set the Site URL to your current self-managed workspace URL.
Go to Administration > Workspace > Settings > File Upload. Confirm that AmazonS3 is already selected as the Storage Type.
Navigate to the Amazon S3 tab and update your S3 configurations accordingly :
- Bucket name
- Access Key
- Secret Access Key
- Region
For more details, refer to Configure Amazon S3 file storage documentation.

Once both settings are saved, your workspace should be fully functional. You can upload new files, view old ones, and confirm that everything is working as expected.

Unique ID change detected

If you get a “Unique ID change detected” warning while accessing your workspace, click New workspace to register your self-managed workspace and avoid configuration conflicts. Contact Rocket.Chat support for further assistance.

You’ve now completed the full migration from a cloud-hosted Rocket.Chat workspace to a self-managed environment. Your messages, channels, files, and user data should all be in place and working as expected. Visit Deploy with Docker & Docker Compose to learn more about your deployment. If you need to scale your workspace, refer to Running Multiple Instances.