Configure file storage settings by going to System Console > Environment > File Storage, or by editing the config.json file as described in the following tables.

Mattermost Academy Learn about file storage

Note

Mattermost currently supports storing files on the local filesystem and Amazon S3 or S3-compatible containers. We have tested Mattermost with MinIO and Digital Ocean Spaces products, but not all S3-compatible containers on the market. If you are looking to use other S3-compatible containers, we recommend completing your own testing.

File storage system#

Also available in legacy Mattermost Enterprise Edition E10 or E20

The type of file storage system used. Can be either Local File System or Amazon S3.

  • local: (Default) Files and images are stored in the specified local file directory.

  • amazons3: Files and images are stored on Amazon S3 based on the access key, bucket, and region fields provided. The driver is compatible with MinIO (Beta) and Digital Ocean Spaces.

  • System Config path: Environment > File Storage

  • config.json setting: ".FileSettings.DriverName:  local”,

  • Environment variable: MM_FILESETTINGS_DRIVERNAME

Local storage directory#

Also available in legacy Mattermost Enterprise Edition E10 or E20

The local directory to which files are written when the File storage system is set to local. Can be any directory writable by the user Mattermost is running as, and is relative to the directory where Mattermost is installed.

Defaults to ./data/.

  • System Config path: Environment > File Storage

  • config.json setting: ".FileSettings.Directory”,

  • Environment variable: MM_FILESETTINGS_DIRECTORY

Note: When File storage system is set to amazons3, this setting has no effect.

Maximum file size#

Also available in legacy Mattermost Enterprise Edition E10 or E20

The maximum file size for message attachments and plugin uploads. This value must be specified in mebibytes in the System Console, and in bytes in the config.json file.

The default is 104857600 bytes (100 mebibytes).

  • System Config path: Environment > File Storage

  • config.json setting: ".FileSettings.MaxFileSize: 104857600",

  • Environment variable: MM_FILESETTINGS_MAXFILESIZE

Warning: Verify server memory can support your setting choice. Large file sizes increase the risk of server crashes and failed uploads due to network disruptions.

Notes:

  • When uploading plugin files, a Received invlaid response from the server error typically indicates that MaxFileSize isn’t large enough to support the plugin file upload, and/or that proxy settings may not be sufficient.

  • If you use a proxy or load balancer in front of Mattermost, the following proxy settings must be adjusted accordingly:

  • For NGINX, use client_max_body_size.

  • For Apache use LimitRequestBody.

Enable document search by content#

Also available in legacy Mattermost Enterprise Edition E10 or E20

Enable users to search the contents of documents attached to messages.

  • true: (Default) Documents are searchable by their content.

  • false: Documents aren’t searchable by their content. When document content search is disabled, users can search for files by file name only.

  • System Config path: Environment > File Storage

  • config.json setting: ".FileSettings.ExtractContent: true",

  • Environment variable: MM_FILESETTINGS_EXTRACTCONTENT

Note: Document content search results for files shared before upgrading to Mattermost Server v5.35 may be incomplete until an extraction command is executed using the mmctl. If this command is not run, users can search older files based on file name only.

You can optionally install the following dependencies to extend content searching support in Mattermost to include file formats beyond PDF, DOCX, and ODT, such as DOC, RTF, XML, and HTML:

  • tidy: Used to search the contents of HTML documents.

  • wv: Used to search the contents of DOC documents.

  • popplerutils: Used to significantly improve server performance when extracting the contents of PDF documents.

  • unrtf: Used to search the contents of RTF documents.

  • JusText: Used to search HTML documents.

If you choose not to install these dependencies, you’ll see log entries for documents that couldn’t be extracted. Any documents that can’t be extracted are skipped and logged so that content extraction can proceed.

Enable searching content of documents within ZIP files#

Also available in legacy Mattermost Enterprise Edition E10 or E20

Enables users to search the contents of compressed ZIP files attached to messages.

  • true: Contents of documents within ZIP files are returned in search results. This may have an impact on server performance for large files. the specified local file directory.

  • false: (Default) The contents of documents within ZIP files aren’t returned in search results.

  • System Config path: Environment > File Storage

  • config.json setting: ".FileSettings.ArchiveRecursion: false",

  • Environment variable: MM_FILESETTINGS_ARCHIVERECURSION

Note: Document content search within ZIP files is available, with mobile support coming soon. Searching document contents adds load to your server. For large deployments, or teams that share many large, text-heavy documents, we recommend you review our hardware requirements, and test enabling this feature in a staging environment before enabling it in a production environment.

Amazon S3 bucket#

Also available in legacy Mattermost Enterprise Edition E10 or E20

The name of the bucket for your S3-compatible object storage instance.

A string with the S3-compatible bucket name.

  • System Config path: Environment > File Storage

  • config.json setting: ".FileSettings.AmazonS3Bucket",

  • Environment variable: MM_FILESETTINGS_AMAZONS3BUCKET

Amazon S3 path prefix#

Also available in legacy Mattermost Enterprise Edition E10 or E20

The prefix you selected for your Amazon S3 bucket in AWS.

A string containing the path prefix.

  • System Config path: N/A

  • config.json setting: ".FileSettings.AmazonS3PathPrefix",

  • Environment variable: MM_FILESETTINGS_AMAZONS3PATHPREFIX

Amazon S3 region#

Also available in legacy Mattermost Enterprise Edition E10 or E20

The AWS region you selected when creating your Amazon S3 bucket in AWS.

A string with the AWS region containing the bucket. If no region is set, Mattermost attempts to get the appropriate region from AWS, and sets it to us-east-1 if none found.

  • System Config path: Environment > File Storage

  • config.json setting: `".FileSettings.AmazonS3Region",

  • Environment variable: MM_FILESETTINGS_AMAZONS3REGION

Note: For MinIO or Digital Ocean Spaces, leave this setting empty.

Amazon S3 access key ID#

Also available in legacy Mattermost Enterprise Edition E10 or E20

A string with the access key for the S3-compatible storage instance. Your EC2 administrator can supply you with the Access Key ID.

  • System Config path: Environment > File Storage

  • config.json setting: ".FileSettings.AmazonS3AccessKeyId",

  • Environment variable: MM_FILESETTINGS_AMAZONS3ACCESSKEYID

Note: This is required for access unless you are using an Amazon S3 IAM Role with Amazon S3.

Amazon S3 endpoint#

Also available in legacy Mattermost Enterprise Edition E10 or E20

The hostname of your S3-compatible instance.

A string with the hostname of the S3-compatible storage instance. Defaults to s3.amazonaws.com.

  • System Config path: Environment > File Storage

  • config.json setting: ".FileSettings.AmazonS3Endpoint: s3.amazonaws.com",

  • Environment variable: MM_FILESETTINGS_AMAZONS3ENDPOINT

Note: For Digital Ocean Spaces, the hostname should be set to <region>.digitaloceanspaces.com, where <region> is the abbreviation for the region you selected when setting up the Space. It can be nyc3, ams3, or sgp1.

Amazon S3 secret access key#

Also available in legacy Mattermost Enterprise Edition E10 or E20

The secret access key associated with your Amazon S3 Access Key ID.

A string with the secret access key for the S3-compatible storage instance.

  • System Config path: Environment > File Storage

  • config.json setting: ".FileSettings.AmazonS3SecretAccessKey",

  • Environment variable: MM_FILESETTINGS_AMAZONS3SECRETACCESSKEY

Enable secure Amazon S3 connections#

Also available in legacy Mattermost Enterprise Edition E10 or E20

Enable or disable secure Amazon S3 connections.

  • true: (Default) Enables only secure Amazon S3 connections.

  • false: Allows insecure connections to Amazon S3.

  • System Config path: Environment > File Storage

  • config.json setting: ".FileSettings.AmazonS3SSL: true",

  • Environment variable: MM_FILESETTINGS_AMAZONS3SSL

Amazon S3 signature v2#

Not available in legacy Mattermost Enterprise Edition E10 or E20

By default, Mattermost uses Signature v4 to sign API calls to AWS, but under some circumstances, v2 is required.

  • true: Use Signature v2 signing process.

  • false: (Default) Use Signature v4 signing process.

  • System Config path: N/A

  • config.json setting: ".FileSettings.AmazonS3SignV2: false",

  • Environment variable: MM_FILESETTINGS_AMAZONS3SIGNV2

See the AWS documentation for information about when to use the Signature v2 signing process.

Enable server-side encryption for Amazon S3#

Also available in legacy Mattermost Enterprise Edition E20

Enable server-side encryption for Amazon S3.

  • true: Encrypts files in Amazon S3 using server-side encryption with Amazon S3-managed keys.

  • false: (Default) Doesn’t encrypt files in Amazon S3.

  • System Config path: Environment > File Storage

  • config.json setting: ".FileSettings.AmazonS3SSE: false",

  • Environment variable: MM_FILESETTINGS_AMAZONS3SSE

Enable Amazon S3 debugging#

Also available in legacy Mattermost Enterprise Edition E10 or E20

Enable or disable Amazon S3 debugging to capture additional debugging information in system logs

  • true: Log additional debugging information is logged to the system logs.

  • false: (Default) No Amazon S3 debugging information is included in the system logs. Typically set to false in production.

  • System Config path: Environment > File Storage

  • config.json setting: ".FileSettings.AmazonS3Trace: false",

  • Environment variable: MM_FILESETTINGS_AMAZONS3TRACE

Select the Test Connection button in the System Console to validate the settings and ensure the user can access the server.

Amazon S3 request timeout#

The amount of time, in milliseconds, before requests to Amazon S3 storage time out.

Default is 30000 (30 seconds).

  • System Config path: N/A

  • config.json setting: ".FileSettings.AmazonS3RequestTimeoutMilliseconds: 30000

  • Environment variable: MM_FILESETTINGS_AMAZONS3REQUESTTIMEOUTMILLISECONDS

Amazon S3 upload part size#

The size, in bytes, of each part in a multi-part upload to Amazon S3.

Numeric value. Default is 5242880 (5MB).

  • System Config path: N/A

  • config.json setting: ".FileSettings.AmazonS3UploadPartSizeBytes: 5242880

  • Environment variable: MM_FILESETTINGS_AMAZONS3UPLOADPARTSIZEBYTES

Note: A smaller part size can result in more requests and an increase in latency, while a larger part size can result in more memory being allocated.

Amazon S3 exported upload part size#

The size, in bytes, of each part in a multi-part exported to Amazon S3.

Numeric value. Default is 104857600 (100MB).

  • System Config path: N/A

  • config.json setting: ".FileSettings.ExportAmazonS3UploadPartSizeBytes: 104857600

  • Environment variable: MM_FILESETTINGS_EXPORTAMAZONS3UPLOADPARTSIZEBYTES

Note: A smaller part size can result in more requests and an increase in latency, while a larger part size can result in more memory being allocated.

Initial font#

Also available in legacy Mattermost Enterprise Edition E10 or E20

The font used in auto-generated profile pictures with colored backgrounds and username initials.

A string with the font file name. Default is nunito-bold.ttf.

  • System Config path: N/A

  • config.json setting: ".FileSettings.InitialFont: nunito-bold.ttf",

  • Environment variable: MM_FILESETTINGS_INITIALFONT

Amazon S3 request timeout#

The amount of time, in milliseconds, before requests to Amazon S3 storage time out.

Default is 30000 (30 seconds).

  • System Config path: N/A

  • config.json setting: ".FileSettings.AmazonS3RequestTimeoutMilliseconds: 30000

  • Environment variable: MM_FILESETTINGS_AMAZONS3REQUESTTIMEOUTMILLISECONDS