Skip to main content

Upload Provider Configuration for Strapi Cloud

Page summary:

Strapi Cloud enforces a 200 MB cap for non-image uploads and memory-based recommendations for images. External storage like S3 or Cloudinary requires plugin setup, security middleware, and Cloud variables.

Strapi Cloud comes with a local upload provider out of the box. However, it can also be configured to use a third-party upload provider, if needed.

Strapi Cloud upload size limits​

Strapi Cloud applies 2 distinct limits to uploads. The first is a hard maximum file size, enforced at the infrastructure level for non-image files. The second is a memory-based recommendation for image files that depends on your CMS settings.

Maximum upload file size for non-image files​

Non-image uploads are capped at 200MB on all Strapi Cloud plans (Free, Essential, Pro, and Scale). The cap is enforced at the infrastructure level and cannot be overridden via the strapi::body middleware configuration.

Image uploads are subject to an additional, memory-driven recommendation that is independent of the non-image cap and varies by image format.

When Responsive friendly upload and Size optimization are both enabled in the Media Library settings, the CMS resizes the source image and generates a set of thumbnails (small, medium, large) in the instance's memory before persisting them. This happens in-process, regardless of the configured upload provider.

Switching to a third-party provider (Amazon S3, Cloudinary, etc.) is not a workaround. The resize and thumbnail generation step still runs inside the Strapi Cloud instance and still requires memory proportional to the source image dimensions.

Actual memory usage depends on the image dimensions, format, and your Media Library settings. The values below are a recommendation, not a hard limit. Uploads above the recommended size are likely to cause the instance to run out of memory and restart.

The recommendation depends on whether Responsive friendly upload and Size optimization are enabled in the Media Library settings:

  • Processing on: both settings enabled, with the default small, medium, and large sizes. Strapi generates the thumbnails in memory, so the safe upload size is lower.
  • Processing off: both settings disabled. The source image is stored as-is with no in-process processing, so the safe upload size is higher.

Recommended maximum image size, expressed in megapixels (MP), per format and plan:

FormatFree & EssentialPro & Scale
JPEG24 MP135 MP
PNG8 MP90 MP
WebP4 MP12 MP
TIFF16 MP125 MP
AVIF66 MP80 MP
Note

The image dimensions in pixels that match a given megapixel count depend on the aspect ratio. For a square image, 1 MP is roughly 1000×1000 px, 4 MP is roughly 2000×2000 px, and 100 MP is roughly 10000×10000 px.

To upload larger images, disable Responsive friendly upload and Size optimization in the Media Library settings. The CMS then stores the source file as-is without in-process processing.

Configuring a third-party upload provider​

Caution

Please be advised that Strapi is unable to provide support for third-party upload providers.

Prerequisites
  • A local Strapi project running on v4.8.2+.
  • Credentials for a third-party upload provider (see Strapi Market).

Configuring a third-party upload provider for use with Strapi Cloud requires 4 steps:

  1. Install the provider plugin in your local Strapi project.
  2. Configure the provider in your local Strapi project.
  3. Configure the Security Middleware in your local Strapi project.
  4. Add environment variables to the Strapi Cloud project.

Install the Provider Plugin​

Using either npm or yarn, install the provider plugin in your local Strapi project as a package dependency by following the instructions in the respective entry for that provider in the Marketplace.

Configure the Provider​

To configure a 3rd-party upload provider in your Strapi project, create or edit the plugins configuration file for your production environment ./config/env/production/plugins.js|ts by adding upload configuration options as follows:


module.exports = ({ env }) => ({
// … some unrelated plugins configuration options
upload: {
   config: {
      // … provider-specific upload configuration options go here
   }
// … some other unrelated plugins configuration options
}
});
Caution

The file structure must match the above path exactly, or the configuration will not be applied to Strapi Cloud.

Each provider will have different configuration settings available. Review the respective entry for that provider in the Marketplace.

Example:

module.exports = ({ env }) => ({
  // ...
  upload: {
    config: {
      provider: 'cloudinary',
      providerOptions: {
        cloud_name: env('CLOUDINARY_NAME'),
        api_key: env('CLOUDINARY_KEY'),
        api_secret: env('CLOUDINARY_SECRET'),
      },
      actionOptions: {
        upload: {},
        uploadStream: {},
        delete: {},
      },
    },
  },
  // ...
});

Configure the Security Middleware​

Due to the default settings in the Strapi Security Middleware you will need to modify the contentSecurityPolicy settings to properly see thumbnail previews in the Media Library.

Caution

On Strapi Cloud, NODE_ENV is always set to production. Changes to the global config/middlewares.ts file are overwritten on each deploy and will not take effect. Place your Security Middleware customizations in config/env/production/middlewares.ts instead. See Middleware Configuration for Strapi Cloud for details.

To do this in your Strapi project:

  1. Navigate to ./config/env/production/middlewares.js or ./config/env/production/middlewares.ts in your Strapi project.
  2. Replace the default strapi::security string with the object provided by the upload provider.

Example:

module.exports = [
  // ...
  {
    name: 'strapi::security',
    config: {
      contentSecurityPolicy: {
        useDefaults: true,
        directives: {
          'connect-src': ["'self'", 'https:'],
          'img-src': [
            "'self'", 
            'data:', 
            'blob:', 
            'market-assets.strapi.io', 
            'res.cloudinary.com'
          ],
          'media-src': [
            "'self'",
            'data:',
            'blob:',
            'market-assets.strapi.io',
            'res.cloudinary.com',
          ],
          upgradeInsecureRequests: null,
        },
      },
    },
  },
  // ...
];
Tip

Before pushing the above changes to GitHub, add environment variables to the Strapi Cloud project to prevent triggering a rebuild and new deployment of the project before the changes are complete.

Strapi Cloud Configuration​

  1. Log into Strapi Cloud and click on the corresponding project on the Projects page.
  2. Click on the Settings tab and choose Variables in the left menu.
  3. Add the required environment variables specific to the upload provider.
  4. Click Save.

Example:

VariableValue
CLOUDINARY_NAMEyour_cloudinary_name
CLOUDINARY_KEYyour_cloudinary_api_key
CLOUDINARY_SECRETyour_cloudinary_secret

Deployment​

To deploy the project and use the third-party upload provider, push the changes from earlier. This will trigger a rebuild and new deployment of the Strapi Cloud project.

Once the application finishes building, the project will use the new upload provider.

Custom Provider

If you want to create a custom upload provider, please refer to the Providers documentation in the CMS Documentation.

Contribute to this page