Migration from MinIO to SeaweedFS

This guide explains how to migrate 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.

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

Set Up the New Backend

If migrating to SeaweedFS, first follow SeaweedFS Setup →. Relution is stopped before the data is copied (see the section “Copy the Data”) and remains stopped until the configuration has been switched.

Ensure both old and new storage backends are running:

docker compose up -d minio seaweedfs

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 the operating system in use.

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 the 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 the 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.

Encrypted object storage: If Server-Side Encryption (SSE-C) → is active, the objects are stored encrypted in the bucket. rclone can only read them with the same key and must write them to the destination with the same key. Otherwise copying fails, or the objects end up unencrypted in the destination and can no longer be read by Relution. For this reason, the algorithm AES256 and the same Base64 key that is configured in Relution are set in the advanced configuration of both remotes (source and dest) (rclone options sse_customer_algorithm and sse_customer_key_base64). The new backend must support SSE-C.

With client-side encryption via AWS KMS, the key data is stored in the object metadata. This metadata must be preserved during copying (rclone option --metadata).

Verify Port Access

rclone accesses the S3 APIs of both backends via the host (http://localhost:9000 and http://localhost:8333). After following Deprecated: MinIO → and SeaweedFS Setup →, the S3 ports are only reachable within the Docker network. For the duration of the migration, they are therefore published on the host in the compose.yaml:

minio:
  ports:
    - "127.0.0.1:9000:9000" # S3 API - for rclone during the migration
    - "9001:9001" # Web console
# ...
seaweedfs:
  ports:
    - "127.0.0.1:8333:8333" # S3 API - for rclone during the migration
    - "127.0.0.1:23646:23646" # Web console

Then recreate the containers with docker compose up -d minio seaweedfs. If rclone runs on a different host, the restriction to 127.0.0.1 is omitted. After the migration, the additional S3 port mappings are removed again.


Copy the Data

  1. Stop Relution to prevent data changes during migration, and verify that only the storage backends are still running:

    docker compose stop relution
    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 the bucket.

  4. Verify the transfer:

    rclone check source:relution dest:relution
    

    Expected output: 0 differences found


Update Relution Configuration

Update the Relution configuration to point to the new backend. Endpoint, access key and secret key change; bucket name and region only if they differ:

SettingOld ValueNew Value
Endpoint (customEndpoint)http://minio:9000http://seaweedfs:8333
Access KeyOld keyNew key
Secret KeyOld secretNew secret
Bucket Name (bucketName)relutionName of the destination bucket (only if it differs)
Region (region)Default eu-west-1Region of the destination bucket (e.g. for AWS S3)
  • If the destination bucket has a different name, the rclone commands use source:<old-bucket> dest:<new-bucket>. The database only stores the object keys, so adjusting bucketName is sufficient.
  • For AWS S3 without a custom endpoint, customEndpoint or RELUTION_STORAGE_S3_CUSTOMENDPOINT is omitted. The endpoint is then derived from the region.
  • The encryption settings (SSE-C key serverSideEncryption.key or keyFile, or KMS) remain unchanged.
  • The destination bucket is used exclusively by this Relution instance. Relution regularly deletes objects in the bucket that are not assigned to one of its own resources.

See Connect object storage → for detailed instructions on where to make these changes.


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 the compose.yaml.

  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
    

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 that the 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.

How helpful was this article?