> ## Documentation Index
> Fetch the complete documentation index at: https://docs.merops.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Bucket

> Connect cloud storage buckets and transfer objects across providers

Buckets are the first cloud resource supported by Merops. The common workflow lets you connect providers, browse buckets and objects, preview object content, create destination buckets, migrate objects, and synchronize data. Other cloud resources, such as databases and compute, can be added as they are developed.

See the [service compatibility overview](/services/compatibility.md) for the current provider matrix. For account setup and credentials, use the relevant guide in the [Providers section](/providers.md).

## Concepts

A **provider** is a connected cloud account or storage service. A **bucket** is a named container for objects; Azure calls the equivalent resource a container. An **object** is stored content identified by its name, often called a key. Folder-like paths may be part of an object name rather than standalone directories.

A **migration** copies objects from a source bucket to a destination bucket. **Synchronization** compares object names and modification times, then copies changes according to a direction. It can copy changes one way, keep both sides in sync, or remove destination-only objects in strict mode.

## Connect a provider

1. Sign in and open **Providers** > **Manage**.
2. Choose the add-provider action and select the provider offered by your application deployment.
3. Import a credential file in the format described on that provider's page and provide the requested display name or metadata.
4. Submit the form, then choose **Configure** on the provider (or double-click its node in map view).
5. Check whether the bucket list loads. A successful list confirms read access to that operation; it does not confirm write access.

Create a dedicated provider identity or key where possible and grant only the access required for the intended buckets and operations. Credential upload accepts a non-empty file up to 10 MiB. The backend encrypts the uploaded credential file with a per-user key before storing it in configured object storage. Removing a provider in Merops does not establish automatic deletion of every historical backup or a credential-rotation workflow; rotate or revoke keys through the provider when required. See [security and data handling](/security-privacy/security/data-handling.md).

## Browse and preview

1. Open **Providers** > **Manage** and choose **Configure** on a connected provider.
2. Select a bucket to load its objects.
3. Select an object to inspect or preview its content.

The application lists names returned by the provider. A verified search, pagination, folder management, bulk download, or object editing workflow is not available in the customer UI. Preview depends on the file type, browser behavior, and provider response. Merops fetches the object content as a whole, so large objects may be impractical to preview. There is no complete supported MIME type list or guarantee of inline rendering for every format.

## Create a bucket

Create a bucket in the provider console when you need to set provider-specific location or access options. Merops can also create a destination bucket during migration:

1. Connect the destination provider.
2. Open **Start Migration** and select the destination connection.
3. Choose an existing bucket or use the create-new option in the destination selector.
4. Start the operation and inspect the destination provider afterward.

Merops' shared bucket creation call supplies a name. Provider-specific settings such as location, retention, and access policy are not part of this workflow.

## Migrate objects

The source identity must be able to list and read the selected bucket's objects. The destination identity must be able to list buckets, create the destination bucket when needed, and write objects. Both providers must be connected and their adapters available.

1. Open **Start Migration**.
2. Choose the source connection and bucket.
3. Choose the destination connection and an existing or new bucket.
4. Start the migration.
5. Confirm success in the application response, then browse the destination bucket and verify its objects.

Merops reads object bytes from the source and writes them to the destination. If an object with the same name already exists at the destination, migration overwrites it. Make a backup if needed. There is no verified per-object progress display or automatic rollback. Object version history, ACLs, policies, and provider-specific settings are not documented as copied.

## Synchronize buckets

Synchronization compares object names and modification times. A manual backend operation defaults an omitted direction to one-way; scheduled synchronization uses configured intervals.

| Mode | Behavior |
| - | - |
| `one-way` | Copies source-only objects and changes from source to destination. Destination-only objects remain. |
| `strict` | Follows source to destination and deletes destination-only objects. Use only when that deletion behavior is intended. |
| `two-way` | Copies source-only or destination-only objects toward the other side. If both sides changed, the newer modification time wins. |

For a manual operation, use the synchronization workflow exposed by your application build. Select two different connected providers and buckets, choose a direction, and start the operation. The backend rejects the same provider ID on both sides and requires a source bucket. Inspect both sides after it completes.

The backend supports scheduled sync intervals of 1, 2, or 3 minutes; 1 hour; 1 day; 1 week; or 30 days. Scheduling requires provider credentials to be available to the running backend. A task may not run if providers are offline or credentials cannot be recovered. The scheduler does not establish an SLA or user-visible per-object progress report.

## Provider operations

These operations are implemented by the provider adapters in the current codebase. Deployments need the matching adapter running and the provider enabled in the application. Account permissions, regions, quotas, naming rules, and provider-side settings may affect each operation.

| Provider | Credential format | Implemented bucket and object operations |
| - | - | - |
| AWS | Access key ID and secret access key; CSV or `KEY=VALUE` text. Optional region. | List buckets/objects, get object and info, put object, create/delete bucket, delete object. |
| Google Cloud | Service account JSON; project ID read from the credential data. | List buckets/objects, get object and info, put object, create/delete bucket, delete object. |
| Azure | Connection string, account name + account key, or account name + tenant/client/client secret. | List containers/objects, get object and info, put object, create/delete container, delete object. |
| Scaleway | `SCW_ACCESS_KEY` and `SCW_SECRET_KEY`; export-style or YAML text. | List buckets/objects, get object and info, put object, create/delete bucket, delete object. |
| OVHcloud | OVH access/secret keys; AWS key aliases also accepted; export-style or YAML text. Optional region and offer. | List buckets/objects, get object and info, put object, create/delete bucket, delete object. |

“Implemented” describes adapter code. It is not a guarantee that every operation works in every account configuration; the repository does not provide a complete cross-provider conformance suite. Object transfer copies content, not all provider-specific metadata or bucket configuration.

## Limitations and troubleshooting

* Merops currently covers object storage. Other resource categories in the compatibility matrix are not available yet.
* Provider adapters exist in the codebase, but a deployment may enable only a subset.
* Provider-specific bucket settings, policies, ACLs, lifecycle rules, version history, and encryption configuration are not documented as copied during migration.
* Transfers operate on object content. The backend does not document resumable multipart transfer or automatic rollback.
* The migration UI does not establish durable job progress or a complete audit history.
* Synchronization uses object names and modification-time comparisons. It does not merge simultaneous edits based on their content or preserve all provider metadata.
* Strict synchronization deletes destination-only objects. Review its effect before using it.
* Preview format coverage and maximum practical object size are unspecified.
* Provider permissions, quotas, naming constraints, regions, and API availability affect results.

If a provider import is rejected, check that the file is non-empty, below 10 MiB, and in the format required by its provider guide. If Merops cannot list buckets, check that credentials are valid, the required list permission is granted, the provider component is running, and the region or endpoint is correct. For migration failures, verify source read and destination write access separately; check for objects already written before retrying. Scheduled sync requires providers to be online and credentials to be available to the backend. Do not include keys, tokens, object contents, or personal data when sharing error details.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.