--- title: "Migrate Rocket Chat from Cloud to Self-Managed" slug: "migrate-from-cloud-hosted-to-self-managed-workspace" description: "Learn how to migrate from a cloud-hosted Rocket Chat workspace to a self-managed deployment. Ensure secure communications, control, and operational resilience." status: "update" updated: 2026-10-30T18:20:50Z published: 2026-10-30T18:20:50Z canonical: "docs.rocket.chat/migrate-from-cloud-hosted-to-self-managed-workspace" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.rocket.chat/llms.txt > Use this file to discover all available pages before exploring further. # 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: 1. **Disable email 2FA on your cloud-hosted workspace**: Go to **Manage → Workspace → Settings → Accounts → Two Factor Authentication** and toggle off **Enable Two Factor Authentication via Email**. This step is vital before requesting your data export to avoid locking out your users. 2. **Request your data export**: Contact [Rocket.Chat support](https://desk.rocket.chat/) 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](/v1/docs/extracting-multi-part-data-exports) to combine them into a single file before proceeding. 3. **Set up a self-managed workspace**: If you haven’t already, deploy a new workspace using [Deploy with Docker & Docker Compose](/v1/docs/deploy-with-docker-docker-compose). To prevent dependency issues during migration, the self-managed workspace must be on the same Rocket.Chat version as your exported cloud-hosted workspace. 4. **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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/create-bucket-overview.html) for more details. ## Step 1: Unpack your data Run the following command to unpack your export: ```bash cat export.tar.gz.part{1..n} | tar xzvf -  #where n is the number of parts ``` - Replace `export.tar.gz.part` with your actual file name if it’s different. - Replace `n` with the number of parts in your export. 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. > [!NOTE] > 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. 1. 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. ```bash docker cp database :/dump ``` Replace `<mongodb-container-name>` with your MongoDB container name. 2. Access the MongoDB container shell by running: ```bash docker exec -it bash ``` Replace `<mongodb-container-name>` with your MongoDB container name. 3. In the MongoDB container, navigate to the `/dump` directory and check that the `<database-folder>` containing your database is present: ```bash cd /dump ls ``` You should see a folder named something like `68224d495816f19310604d9b` which is your `<database-folder>`. 4. Run the following command to drop the default `rocketchat` database and restore the exported data: ```bash mongorestore --drop --db rocketchat /dump/ ``` Replace `<database-folder>` with the actual folder name you saw in the previous step (e.g. `68224d495816f19310604d9b`). 5. After the restore process is completed successfully, exit the MongoDB container shell and restart the Rocket.Chat service: ```bash 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. 1. Create a subfolder in `files/` named after your `<database-folder>`, then move the `avatars` and `uploads` folders into it: ```bash mkdir files/ mv files/avatars files/uploads files// ``` Replace `<database-folder>` with the actual folder name (e.g. `68224d495816f19310604d9b`). This creates the structure Rocket.Chat expects: ```plaintext files/  └── /      ├── avatars/      └── uploads/ ``` This step ensures Rocket.Chat can correctly reference these files using the folder name as a namespace. 2. 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](https://docs.aws.amazon.com/AmazonS3/latest/userguide/upload-objects.html#upload-objects-procedure) for more details on uploading objects. 3. [Create a new policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create-console.html#access_policies_create-json-editor) in AWS for a user to read and write files to the bucket: ```json {    "Version": "2012-10-17",    "Statement": [        {            "Effect": "Allow",            "Action": [                "s3:GetObject",                "s3:PutObject",                "s3:ListBucket",                "s3:DeleteObject"            ],            "Resource": [                "arn:aws:s3:::",                "arn:aws:s3:::/*"            ]        }    ] } ``` Replace `<bucket-name>` with your actual S3 bucket name. 4. [Create a new IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html) in AWS and [attach the policy you created](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html#users_change_permissions-add-console) earlier to the user. [Generate an access key](https://docs.aws.amazon.com/IAM/latest/UserGuide/access-keys-admin-managed.html#admin-create-access-key) for the user and copy the **Access key** and **Secret access key**. > [!NOTE] > 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. > [!WARNING] > The commands in this step are for Rocket.Chat 9.0.0 and later. If your workspaces run an earlier version, use the alternative command provided below each update. 1. Run this command to access your MongoDB shell and interact with your database: ```bash docker exec -i mongosh ``` Replace `<mongodb-container-name>` with your MongoDB container name. Then switch to the Rocket.Chat database: ```plaintext use rocketchat ``` 2. Update the path and URL for all **previously uploaded files** to match the new structure in your S3 bucket with these commands: ```plaintext db.rocketchat_uploads.updateMany({ "AmazonS3.path": /^/ }, [{ $set: { "AmazonS3.path": { "$concat": ["/uploads/", "$_id"]} } }]) db.rocketchat_uploads.updateMany({ "url": /^https:\/\/\// }, [{ $set: { "url": { "$concat": ["/file-upload/", "$_id", "/", "$name"]} } }]) ``` If your workspaces run a **version earlier than 9.0.0**, run this command instead of the second command above: ```plaintext db.rocketchat_uploads.updateMany({ "url": /^https:\/\/\// }, [{ $set: { "url": { "$concat": ["/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-WORKSPACE-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`). 3. Update the path and URL for all **previously uploaded avatars** to match the new structure in your S3 bucket with these commands: ```plaintext db.rocketchat_avatars.updateMany({ "AmazonS3.path": /^/ }, [{ $set: { "AmazonS3.path": { "$concat": ["/avatars/", "$_id"]} } }]) db.rocketchat_avatars.updateMany({ "url": /^https:\/\/\// }, [{ $set: { "url": { "$cond": [{ "$ifNull": ["$rid", false] }, { "$concat": ["/avatar/room/", "$rid"] }, { "$concat": ["/avatar/uid/", "$userId"] }] } } }]) ``` If your workspaces run a **version earlier than 9.0.0**, run this command instead of the second command above: ```plaintext db.rocketchat_avatars.updateMany({ "url": /^https:\/\/\// }, [{ $set: { "url": { "$concat": ["/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-WORKSPACE-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`). 4. Exit the MongoDB shell and restart the Rocket.Chat service: ```bash 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. 1. Go to **Manage → Workspace → Settings → General** and set the **Site URL** to your current self-managed workspace URL. 2. Go to **Manage → Workspace → Settings → File Upload**. Confirm that **AmazonS3** is already selected as the **Storage Type**. 3. Select the Amazon S3 tab and update your S3 configurations accordingly: For more details, see [File Upload Settings](/v1/docs/file-upload#configure-amazon-s3-file-storage1). - Bucket name - Access Key - Secret Access Key - Region 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](https://desk.rocket.chat/) 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](/v1/docs/deploy-with-docker-docker-compose) to learn more about your deployment. If you need to scale your workspace, refer to [Running Multiple Instances](/v1/docs/running-multiple-instances).