Attachment Storage Configuration

Attachment storage methods

Local file system

By default, Confluence stores attachments in the attachments directory within the configured Confluence home folder.

S3 object storage

Starting from Confluence 8.1, you can also store your attachment data on Amazon S3 object storage. We recommend this method if your team has large or increasing data needs and requires the ability to scale efficiently. Learn more about configuring S3 object storage.

Migrating your attachment data

From the file system to S3 object storage

If you have existing attachment data and you want to use Amazon S3, you should migrate attachments to an S3 bucket for Confluence to consume.

To migrate, follow the steps below:

1. Check that you're using Confluence 8.1 or newer.
2. Check that the migration to v4 hierarchical attachment storage structure is complete. Learn how to do this
3. Create a new Amazon S3 bucket for Confluence (follow step 1 on Configuring S3 object storage).

4. Migrate the v4 attachment data (${confluenceHome}/attachments/v4) from its physical source to the root prefix confluence/attachments/ in the S3 bucket.
   For example:
   

   File system	${confluenceHome}/attachments/v4/14/0/327689/327689.1
   S3	<S3_Bucket>/confluence/attachments/v4/14/0/327689/327689.1

   The physical location of this data is dependent on your environment. For example, clustered environments typically host this data in a network file system (NFS) as a shared mount. You'll need to consider you setup and the amount of attachment data that needs to be migrated. In general, we recommend using Amazon DataSync for migration. Learn how to do this

5. Wait for the migration to complete.

6. Configure your Confluence node(s) one by one with AWS authentication details and your S3 configuration (follow steps 2 and 3 on Configuring S3 object storage).

   1. Consider putting Confluence into read-only mode to avoid data creation until all node(s) are configured for S3.

   2. After providing the relevant configuration, each node will require a restart.

   3. During this process, if attachments are created on nodes that have yet to be configured for S3, then the attachment data won't be available to those nodes that have been configured for S3.

7. Verify that Confluence is using S3 object storage with the following steps:

   1. Go to Administration menu , then General Configuration. > System Information

   2. Next to 'Attachment Storage Type', you'll see 'S3'

   3. Additionally, next to 'Java Runtime Arguments', both the bucket name and region system properties and their respective values will be visible.

8. Re-run the original DataSync job to perform a final sync. This should be done after all the nodes have been configured to ensure all attachment data is migrated.

At this stage, attachment data will be read and written from AWS S3.

Troubleshooting

As the source file system data is not altered or removed by DataSync, Confluence can be reverted back to reading and writing attachment data from the file system. To do this, remove the configuration below from your setenv.sh and/or confluence.cfg.xml, and restart Confluence:

• confluence.filestore.attachments.s3.bucket.name

• confluence.filestore.attachments.s3.bucket.region

If you are reverting back to the original file system, any data written to S3 will need to be synced back to the file system manually by the Confluence administrator.