Configuration of S3-Compatible Storage for 1C-Bitrix
The disk on the server is running out. Or you need to spread across multiple servers and sync uploaded files between them. Moving /upload/ to S3-compatible storage (MinIO, Selectel, VK Cloud, Cloudflare R2) solves both problems — but only if configured correctly, otherwise Bitrix starts recording file paths incorrectly.
main.cloudstorages Module
Bitrix supports cloud storage through the main.cloudstorages module. It abstracts file work through providers. For S3-compatible storage, the amazon provider is used (API-level compatibility with S3).
Provider configuration is done in /bitrix/admin/main_cloud_storage.php. Parameters for S3-compatible storage:
-
Endpoint URL — service URL (for MinIO:
http://minio:9000, for Selectel:https://s3.selectel.ru) - Key — Access Key ID
- Secret — Secret Access Key
- Bucket — bucket name
-
Region — region (for custom S3 often
us-east-1)
Configuration in code (for setup automation):
\Bitrix\Main\Config\Option::set('main', 'cloud_storage_active', 'Y');
\Bitrix\Main\Config\Option::set('main', 'cloud_storage_provider', 'amazon');
\Bitrix\Main\Config\Option::set('main', 'cloud_storage_endpoint', 'https://s3.example.com');
\Bitrix\Main\Config\Option::set('main', 'cloud_storage_access_key', 'ACCESS_KEY');
\Bitrix\Main\Config\Option::set('main', 'cloud_storage_secret_key', 'SECRET_KEY');
\Bitrix\Main\Config\Option::set('main', 'cloud_storage_bucket', 'bitrix-uploads');
\Bitrix\Main\Config\Option::set('main', 'cloud_storage_path', 'upload/');
Path Style vs Virtual Hosted Style
The most common problem when connecting non-AWS S3 is incorrect bucket addressing. AWS uses virtual hosted style: https://bucket.s3.amazonaws.com/key. Most S3-compatible services support path style: https://s3.example.com/bucket/key.
The standard Bitrix module uses virtual hosted style. For services that don't support it (e.g., MinIO on local network without wildcard DNS), you need to patch the provider class /bitrix/modules/main/lib/cloudstorages/amazon.php — add the use_path_style_endpoint: true parameter when initializing AWS SDK:
$s3Client = new \Aws\S3\S3Client([
'version' => 'latest',
'region' => $region,
'endpoint' => $endpoint,
'use_path_style_endpoint' => true,
'credentials' => [
'key' => $accessKey,
'secret' => $secretKey,
],
]);
Synchronization of Existing Files
After connecting storage, Bitrix starts uploading new files to S3, but old ones remain local. For migration, use the built-in utility: /bitrix/admin/main_cloud_copy.php. It launches an agent that transfers files from /upload/ to storage in batches and updates paths in b_file.
During migration, it's important: the SUBDIR field in b_file stores the relative file path. After migration to S3, paths become bucket URLs. If migration is interrupted halfway, some files will be in S3, some locally. Bitrix determines the file source by the EXTERNAL_ID field in b_file — if filled, the file is considered cloud-based.
Public Access and CDN
Files in S3 must be publicly accessible for direct image links. Setting bucket policy for public read:
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": "*",
"Action": "s3:GetObject",
"Resource": "arn:aws:s3:::bitrix-uploads/*"
}]
}
To connect CDN in front of the bucket (CloudFront, Cloudflare) in module settings, specify the CDN_URL parameter — Bitrix will form public URLs through CDN, and writing to S3 will be direct.
Cache and Temporary Files
The /bitrix/cache/ directory cannot be moved to S3 — it degrades performance. Cache should remain local or on fast network storage (NFS, Redis for managed cache). Only /upload/ — user content — is moved to S3.