Steps

To configure Amazon S3 or an S3-compatible object store¹ as blob store that is used for storing data like attachments in XWiki, follow the following steps:

1. If you're upgrading from a version of XWiki below 11.8, make sure you've started XWiki at least once with a more recent version to apply old filesystem store migrations.
2. Go to the extension manager and install the "S3 Blob Store" extension on the farm if you're not using a custom WAR that includes it.
3. Make sure you have a current backup of your XWiki installation, in particular of the permanent directory to be able to restore the previous state in the case of an error.
4. Edit xwiki.properties and uncomment and set the following properties:
   1. Set store.blobStoreType to s3.
   2. Set store.s3.bucketName to the name of the bucket that you want to use for XWiki. The bucket needs to exist, XWiki won't create any bucket.
   3. Set store.s3.region to the AWS region where the S3 bucket is located. For most S3-compatible APIs you can leave the default value of us-east-1.
   4. Set store.s3.accessKey to the access key for authenticating to your S3 bucket. This could also be the username.
   5. Set store.s3.secretKey to the secret key for authenticating to your S3 bucket. This is like a password, you could also use system property or environment variable to avoid storing the secret key in a configuration file.
   6. If you're not using Amazon S3 but an S3-compatible store, set store.s3.endpoint to the AWS endpoint URL of the S3-compatible service XWiki should use.
   7. Set store.s3.pathStyleAccess to true if you want to use path-style access. This is required for many s3-compatible services.
   8. Configure connection timeouts, the maximum number of parallel connections and the maximum number of retries if desired (store.s3.maxConnections, store.s3.connectionTimeout, store.s3.socketTimeout, store.s3.requestTimeout, store.s3.maxRetries).
   9. You can configure a prefix that will be added to every object key with the store.s3.keyPrefix configuration option. This can be useful If the bucket shall not only be used by XWiki.
   10. Configure the maximum upload part size store.s3.multipartPartUploadSizeMB depending on the maximum size of all attachments in a wiki page and the available RAM. When an object is uploaded to S3, XWiki keeps a buffer of the configured size in memory. As the number of parts is limited to 10k, the default (and minimum setting) of 5MB gives you a maximum object size of 50GB. An object could be an attachment in a wiki page or the XML-serialized version of a wiki page including all attachments for deleted wiki pages. The maximum part size is 5GB, but as the maximum object size in S3 is 5TB, upload sizes above 512MB won't give you larger total upload sizes.
   11. If desired, configure the copy part size store.s3.multipartCopySizeMB. This should generally not be necessary as the default of 512MB should be enough for all needs.
5. If you're using a clustered setup, disable all nodes except for one.
6. Restart XWiki.
7. Wait for the migration from the file system store to s3. You should see a log message "Starting blob store migration for [store/file] (source: [filesystem], target: [s3])." at the start and "Completed blob store migration for [store/file]." at the end.
8. If you're using a clustered setup, you can remove the shared file system now and start again all nodes.

1. ^ Not all S3-compatible object stores work with XWiki, see the explanation.