Migration Guide

Introduction #

This guide explains how to migrate your Relution data from one object storage backend to another. Common scenarios include:

• Migrating from MinIO to SeaweedFS (MinIO is no longer maintained)
• Moving from cloud provider to self-hosted (or vice versa)
• Switching cloud providers

The examples below demonstrate a migration from MinIO to SeaweedFS, but the steps can be adapted for any S3-compatible source and destination.

Overview #

The migration process consists of four steps:

1. Set up the new storage backend
2. Copy data from old to new storage
3. Update Relution configuration
4. Remove the old backend

Prerequisites #

• Access to both storage backends simultaneously
• The rclone command-line tool (installation guide)
• Credentials for both storage backends

Step 1: Set Up the New Backend #

If migrating to SeaweedFS, follow our SeaweedFS Setup Guide first, but do not start Relution yet.

Ensure both old and new storage backends are running:

docker compose up -d minio seaweedfs

Step 2: Configure rclone #

The rclone tool provides a fast and reliable way to copy data between S3-compatible backends.

Install rclone #

Follow the instructions at rclone.org/install for your operating system.

Create Remote Configurations #

Run the configuration wizard:

rclone config

Configure the source (MinIO):

1. Type n for new remote
2. Name: source
3. Storage type: Select s3
4. Provider: Select Minio (or Other for generic S3)
5. Enter your access key and secret key
6. Endpoint: http://localhost:9000
7. Accept defaults for remaining options
8. Confirm with y

Configure the destination (SeaweedFS):

1. Type n for new remote
2. Name: dest
3. Storage type: Select s3
4. Provider: Select Other
5. Enter your new access key and secret key
6. Endpoint: http://localhost:8333
7. Accept defaults for remaining options
8. Confirm with y

Type q to exit the configuration.

Verify Port Access #

Ensure the S3 API ports are exposed on your host. Check your compose.yml:

minio:
  ports:
    - "9000:9000" # S3 API - must be accessible
    - "9001:9001" # Web console
# ...
seaweedfs:
  ports:
    - "8333:8333" # S3 API - must be accessible
    - "23646:23646" # Web console

Step 3: Copy the Data #

1. Verify Relution is stopped to prevent data changes during migration:

   docker compose ps  # Should show storage backends, but NOT relution
   

2. Start the transfer:

   rclone copy source:relution dest:relution --progress
   

3. Wait for completion. Transfer time depends on the amount of data in your bucket.

4. Verify the transfer:

   rclone check source:relution dest:relution
   

   Expected output: 0 differences found

Step 4: Update Relution Configuration #

Update your Relution configuration to point to the new backend. You’ll need to change:

See Configure Relution for detailed instructions on where to make these changes.

Step 5: Verify and Clean Up #

1. Start Relution:

   docker compose up -d relution
   

2. Verify functionality: Log into Relution and confirm that apps and resources load correctly.

3. Remove the old backend (only after thorough verification):

   docker compose down minio  # Stop the old service
   

4. Clean up configuration: Remove the old service from your compose.yml.

5. Delete old data: Remove the old storage volume or directory (e.g., ./volumes/minio/data).

6. Clean up rclone: Optionally remove the rclone configuration:

   rclone config delete source
   rclone config delete dest
   

Troubleshooting #

Connection Refused / Timeout #

Ensure the S3 API ports are exposed and not blocked by a firewall or network segmentation. Test connectivity:

curl http://localhost:8333  # Should return an S3 error

Access Denied / 401 / 403 #

Verify your credentials are correct and the user has access to the bucket.

Missing Files After Migration #

Re-run the verification:

rclone check source:relution dest:relution

If differences are found, run rclone copy again; it will only transfer missing files.