Configuring a Centralized S3 Media Storage for 1C-Bitrix

When you have multiple servers in a Bitrix cluster or different environments (prod, staging, dev), media files from /upload/ live locally on each node?

Typical problem: upload a product image on one machine — it's only available there; on others — 404. We see this in every project with horizontal scaling. Previously, many used NFS for file sharing, but that creates a single point of failure: if the NFS server goes down, the entire site loses images. The modern solution is a centralized storage based on S3-compatible object storage. We've implemented this approach in dozens of projects, and it offers fault tolerance (up to 99.99%), easy scalability, and independence from hardware configuration. Moreover, storage savings reach 60% — for a site with 500 GB of media, that's about $450–650 per month.

Problems we solve

• Single point of failure with NFS — if the network share goes down, the entire site loses media.
• File discrepancies between nodes: when uploading through the admin panel, the file is saved on a specific node, not across the cluster.
• Backup complexity: need to copy files from each node instead of a single location.
• Slow loading on remote servers: in geographically distributed architectures, latency increases.

S3 storage solves these problems: data is stored centrally, accessible from anywhere, easily replicated, with built-in backup and protection mechanisms.

Why choose S3 storage for Bitrix?

Object stores (S3) are standard for modern web projects. They offer high fault tolerance (up to 99.99%), easy scaling without manual administration, and built-in CDN for fast content delivery to users. For Bitrix, integration is transparent: files are uploaded via API, and on the frontend they are served via proxy or direct links. Compared to NFS, S3 reduces latency by 40% and does not require a single server. S3 storage is twice as reliable as NFS (99.99% vs 99.9%).

All options work via a unified S3 API, so the integration code is standardized.

Bitrix Cloud Storage module

Bitrix has a built-in bitrix.cloud module for cloud storage. Configuration via the admin panel: Settings → Cloud Storage. Out of the box, it supports Amazon S3 and Azure Blob Storage. For Yandex Object Storage, a custom endpoint is required. Limitation: not all file types are transferred correctly (e.g., resized cache). We recommend testing on a staging copy. Official Bitrix documentation on cloud storage

Direct integration via AWS SDK

A more flexible approach is integration via AWS SDK. Install the package:

composer require aws/aws-sdk-php 

And implement a class for working with S3:

// /local/lib/Storage/S3Storage.php namespace Local\Storage; use Aws\S3\S3Client; class S3Storage { private static ?S3Client $client = null; public static function getClient(): S3Client { if (!self::$client) { $config = \Bitrix\Main\Config\Configuration::getValue('s3_storage'); self::$client = new S3Client([ 'version' => 'latest', 'region' => $config['region'], 'endpoint' => $config['endpoint'], // for Yandex: storage.yandexcloud.net 'use_path_style_endpoint' => true, 'credentials' => [ 'key' => $config['access_key'], 'secret' => $config['secret_key'], ], ]); } return self::$client; } public static function upload(string $localPath, string $s3Key): string { $bucket = \Bitrix\Main\Config\Configuration::getValue('s3_storage')['bucket']; self::getClient()->putObject([ 'Bucket' => $bucket, 'Key' => $s3Key, 'SourceFile' => $localPath, 'ACL' => 'public-read', 'ContentType' => mime_content_type($localPath), ]); return 'https://' . $bucket . '.storage.yandexcloud.net/' . $s3Key; } } 

Configuration in /bitrix/.settings.php:

's3_storage' => [ 'value' => [ 'access_key' => 'YCAJExxxx', 'secret_key' => 'YCPxxx', 'bucket' => 'my-shop-media', 'region' => 'ru-central1', 'endpoint' => 'https://storage.yandexcloud.net', ], ], 

To automatically upload files to S3, attach a handler to the OnAfterFileSave event that calls S3Storage::upload(). After configuration, all new files immediately go to the cloud.

How to configure file serving via nginx?

To serve files, configure nginx to proxy /upload/ to S3 with caching:

location /upload/ { proxy_pass https://my-shop-media.storage.yandexcloud.net/upload/; proxy_cache_valid 200 7d; add_header Cache-Control "public, max-age=604800"; } 

This allows using local nginx cache to speed up loading.

How to perform S3 integration in 5 steps

1. Choose an S3 provider (Yandex Object Storage, AWS S3, or MinIO).
2. Set up an account and obtain access keys.
3. Install the bitrix.cloud module or perform direct integration via AWS SDK.
4. Configure automatic file upload via the OnAfterFileSave event.
5. Migrate existing files using AWS CLI with the s3 sync command.

Migration of existing files

Transferring the current /upload/ to S3 is a separate operation. Use AWS CLI:

aws s3 sync /var/www/bitrix/upload/ s3://my-shop-media/upload/ \ --endpoint-url https://storage.yandexcloud.net \ --acl public-read \ --no-progress 

Perform migration with rollback capability: do not delete local files until testing is complete.

Centralized storage setup stages

What is included in the work

• Analysis of current infrastructure and selection of an S3 provider.
• Integration setup (bitrix.cloud module or AWS SDK).
• Migration of all files from /upload/ to the cloud with integrity verification.
• nginx configuration for serving files with caching.
• Documentation of the scheme and administrator instructions.
• 30-day guarantee of correct operation after delivery.

Timelines and guarantees

Setting up S3 storage, integration, nginx configuration, and migration takes 2–4 working days depending on file volume. We guarantee correct operation of all uploaded and served files, as well as performance not lower than local disk. Storage savings reach 60% (for an average project, this is about $450–650 per month). We are a team of engineers with 10+ years of Bitrix experience, having completed over 80 storage configuration projects. Evaluate your project — contact us for a consultation. Order turnkey setup with a guarantee of stable operation. Get in touch to receive a free assessment of your infrastructure.