Understanding Uploads, Images, and Attachments

documentation admins
1

:discourse: This explanation guide will walk admins through everything they need to know about uploading images and attachment on their Discourse site.

Discourse provides robust support for uploads, images, and attachments, allowing users to enrich their posts and share files with others. Understanding how uploads, images, and attachments work in Discourse can help you to better manage your community and provide a better user experience.

Uploading Files and Images

In Discourse, users can upload files and images directly to their posts using the upload button in the post editor.

The upload button’s icon changes depending on the allowed types of uploads. If only image file types are allowed, the upload icon will appear as an image icon.

image
image823Ă—94 2.82 KB

However, if other file types are allowed, the upload icon will appear as a general upload icon.

image
image767Ă—82 2.49 KB

Discourse also supports uploading embedding images from other websites, and when an image is uploaded, Discourse creates multiple sizes of the image, which are used in different contexts around the site.

image
image1735Ă—350 24.6 KB

Every time a user uploads a new file to the forum, Discourse saves the file in the server’s /var/discourse/shared/standalone/uploads/default/ folder.

Allowed File Types

By default, Discourse allows image file types (jpg, jpeg, png, gif, heic, heif, webp, and avif).

Admins can also add more file extensions to the authorized extensions and authorized extensions for staff site settings to allow other types of files, such as .pdf, .docx, .mp3, etc.

image
image1049Ă—302 15.3 KB

:person_tipping_hand: Removing all file types from the list of authorized extensions will disable uploads on your site. If you don’t want to store uploads on your site’s server, you can disable them, tell your users to only publish uploads to external sites, and then share the links to the uploads on your site.

Allowed File Sizes

The default maximum size for images is set to 4096 kB (4 MB). This limit can be adjusted by changing the max image size kb site setting based on the needs of your community.

The default maximum size for non-image uploads is set to 8192kB (8 MB). This limit can be adjusted by modifying the max attachment size kb site setting.

image
image1058Ă—327 17.1 KB

:person_tipping_hand: The maximum kb size for both of these settings is 30720 kB / 30 MB.

Large Files

If you are sharing many files or very large files regularly, we recommend that you use Google Drive, Dropbox or another cloud file sharing service. You can also use a streaming service like YouTube or SoundCloud to host your large media files. You can then get a link from there and paste it into your post. Insert the link on its own line, surrounded by empty lines, to display the file in a media player if supported, or a summary preview.

Deleting Uploads

There is no file management interface provided in Discourse. To remove files, delete the posts that contain them or edit the posts to remove the attachment links. Orphaned files will be removed automatically after a 48 hour grace period.

See Cleaning up Uploads and Purging Uploads from S3 for additional details about deleting uploads on your site.

File Uploads and S3 Storage

:discourse: The following section is only applicable for self-hosted installations and Enterprise hosted sites.

Discourse allows you to configure S3 compatible Object Storage providers to store uploads.

You can follow these guides on how to set up file and image uploads to S3 or configure an S3 compatible object storage provider for uploads: Setting up file and image uploads to S3 and Configure an S3 compatible object storage provider for uploads.

S3 Uploads and Site Backups

If you’re using S3 for uploads, you might want to consider how this affects your backup strategy. Discourse allows you to configure automatic backups, and you can choose to store these backups on S3. However, if you’re using S3 for uploads and backups, you might need to consider the impact on bandwidth and storage costs. For more information, check out this topic: Configure automatic backups for Discourse.

S3 Uploads and CDNs

If you’re using a CDN in conjunction with S3 uploads, you’ll need to ensure that this is correctly configured. Discourse has a guide on how to enable a CDN for your Discourse, which covers the use of S3: Enable a CDN for your Discourse.

Secure Uploads

Discourse has a feature called “Secure Uploads” which restricts access to uploaded files so that only users with the necessary permissions can view or download the files. This is particularly useful for private communities or for content that should not be publicly accessible.

To use this feature, you must have S3 uploads enabled on your site and your S3 bucket should not have a public bucket policy. All existing uploads should have a public-read S3 ACL.

However, enabling secure uploads can increase the complexity of your setup, potentially impact site performance, and increase the size of your backups.

To learn more about enabling secure uploads on your site, see: Secure Uploads

Additional Topics

9 Likes
2

Hello. I have several questions:

  1. Are images stored in one folder or are they sorted in folders by date, like in WordPress?
  2. When deleting a topic, images and attachments from this topic are also deleted?
1 Like
3

That’s a good question. They are stored as a hash of the file so the same for uploaded twice (even with different names) will have just one copy. This should get added the the OP.

I believe this was covered.

4 Likes
4

Is it possible to upload large files automatically to a cloud file sharing service so that the user don’t have to do anything?

If I use S3 is it possible to upload large files directly?

2 Likes
5

I also have this idea, I am trying to develop a large file upload plugin. It will be directly uploaded to the cloud file sharing service.

1 Like