Wiki source code of Configure S3 as Blob Store
Last modified by Michael Hamann on 2026/02/26 11:09
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | To configure Amazon S3 or an S3-compatible object store{{footnote}}Not all S3-compatible object stores work with XWiki, see [[the explanation>>page:../WebHome]].{{/footnote}} as [[blob store>>documentation.xs.admin.store.blob.WebHome]] that is used for storing data like attachments in XWiki, follow the following steps: | ||
| 2 | |||
| 3 | 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. | ||
| 4 | 1. 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. | ||
| 5 | 1. Make sure you have a current backup of your XWiki installation, in particular of the [[permanent directory>>path:/xwiki/bin/view/Documentation/AdminGuide/Configuration/#HPermanentDirectory]] to be able to restore the previous state in the case of an error. | ||
| 6 | 1. Edit ##xwiki.properties## and uncomment and set the following properties: | ||
| 7 | 11. Set ##store.blobStoreType## to ##s3##. | ||
| 8 | 11. 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. | ||
| 9 | 11. 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. | ||
| 10 | 11. Set ##store.s3.accessKey## to the access key for authenticating to your S3 bucket. This could also be the username. | ||
| 11 | 11. 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>>extensions:Extension.Configuration Module||anchor="HSystempropertiesandenvironmentvariables"]] to avoid storing the secret key in a configuration file. | ||
| 12 | 11. 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. | ||
| 13 | 11. Set ##store.s3.pathStyleAccess## to true if you want to use path-style access. This is required for many s3-compatible services. | ||
| 14 | 11. 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##). | ||
| 15 | 11. 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. | ||
| 16 | 11. 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. | ||
| 17 | 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. | ||
| 18 | 1. If you're using a clustered setup, disable all nodes except for one. | ||
| 19 | 1. Restart XWiki. | ||
| 20 | 1. 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. | ||
| 21 | 1. If you're using a clustered setup, you can remove the shared file system now and start again all nodes. | ||
| 22 | |||
| 23 | {{putFootnotes/}} |
