Extension:AWS

MediaWiki extensions manual

AWS Release status: stable
Implementation	File repository
Description	Stores MediaWiki images in Amazon S3
Author(s)	Edward Chernenkotalk
Latest version	0.14.0 (2026-01-11)
Compatibility policy	Master maintains backward compatibility.
MediaWiki	1.43+
PHP	8.1+
Database changes	No
Composer	edwardspec/mediawiki-aws-s3
Parameters $wgAWSCredentials $wgAWSRegion $wgAWSBucketName $wgAWSBucketDomain $wgAWSRepoHashLevels $wgAWSRepoDeletedHashLevels $wgAWSBucketTopSubdirectory
Hooks used MediaWikiServices
License	GNU General Public License 2.0 or later
Download	GitHub: project page git repository URL commit history Note: No localisation updates are provided by translatewiki.net .

The AWS extension allows MediaWiki to use Amazon S3 (or any compatible API, such as Apache CloudStack or Digital Ocean Spaces) instead of the local images/ directory to store a wiki's uploaded files.

Why is this needed?

When images are in S3:

1. Amazon EC2 instance, which runs MediaWiki, does not contain any important data and can be created/destroyed by Autoscaling.
2. Visitors download images directly from Amazon S3 (which is fast), not from Amazon EC2 (where network performance depends on instance type, etc.).

Alternatives

Instead of using Amazon S3 (and this extension), you can create an Amazon EFS drive and mount it to $wgUploadDirectory . It is recommended for small wikis.

Installation

For modern versions of MediaWiki (1.35+), use the following instructions:

1. Download the extension:

   git clone --depth 1 https://github.com/edwardspec/mediawiki-aws-s3.git AWS

2. Move the AWS directory to the "extensions" directory of your MediaWiki, e.g., /var/www/html/w/extensions (assuming MediaWiki is in /var/www/html/w).
3. Create the file /var/www/html/w/composer.local.json with the following contents:

   {
   	"extra": {
   		"merge-plugin": {
   			"include": [
   				"extensions/AWS/composer.json"
   			]
   		}
   	}
   }
   

4. Run composer update from /var/www/html/w (to download dependencies). If you do not have Composer installed, see Composer for instructions on installing it.
5. Create an S3 bucket for images, e.g. wonderfulbali234.

   Note: this name will appear in the image URLs.

6. Authorize MediaWiki to access Amazon S3:
   1. If your EC2 instance has an IAM instance profile (recommended), copy everything from "Needed IAM permissions" (see below) to an inline policy of the IAM role. See https://console.aws.amazon.com/iam/home#/roles
   2. If your EC2 instance does not have an IAM profile, obtain a key/secret for AWS API. You will need to write it in LocalSettings.php (see below).
7. Modify LocalSettings.php (see below).

See https://github.com/edwardspec/mediawiki-aws-s3/blob/master/README.md for more details.

Configuration

Step 1: configure LocalSettings.php

wfLoadExtension( 'AWS' );

// Configure AWS credentials.
// THIS IS NOT NEEDED if your EC2 instance has an IAM instance profile.
$wgAWSCredentials = [
	'key' => '<somekey>',
	'secret' => '<somesecret>',
	'token' => false
];

// Configure AWS region, e.g.,
// replace <someregion> with e.g. us-east-1 for Northern Virginia
$wgAWSRegion = '<someregion>'; 

// Configure AWS bucket name
// Replace <somename> with the name of your S3 bucket, e.g. wonderfulbali234.
$wgAWSBucketName = '<somename>';

// Configure required hash levels
// 2 means that S3 objects will be named a/ab/Filename.png
// (same as when MediaWiki stores files in local directories)
$wgAWSRepoHashLevels = '2'; # Default 0

// Configure required hash levels
// 3 means that deleted S3 objects will be named a/b/c/Filename.png
// (same as when MediaWiki stores deleted files in local directories)
$wgAWSRepoDeletedHashLevel = '3'; # Default 0

// If your AWS account uses hundreds of buckets
// (potentially approaching the limit of 1000 buckets per account),
// it is possible to avoid creating a separate bucket for every wiki
// with the following configuration:
$wgAWSBucketTopSubdirectory = "/$wgDBname"; # leading slash is required

Step 2: needed IAM permissions

Visit the IAM Management Console - https://console.aws.amazon.com/iam/home - and add "Inline policy" to the IAM role of your Webserver.

The inline policy should contain (within the Statement array, as in this example) the following permissions (replace <something> with the name of your S3 bucket, e.g., wonderfulbali234):

{
        "Effect": "Allow",
        "Action": [
                "s3:*"
        ],
        "Resource": [
                "arn:aws:s3:::<something>/*"
        ]
},
{
        "Effect": "Allow",
        "Action": [
                "s3:Get*",
                "s3:List*"
        ],
        "Resource": [
                "arn:aws:s3:::<something>"
        ]
}

Debug log

For troubleshooting purposes, you can enable the debug log:

$wgDebugLogGroups['FileOperation'] = '/path/to/some/writable/file.log';

This log records every S3 operation (GetObject, PutObject, etc.), even if it was successful, and the error messages if it failed. This log can help you spot misconfigurations (e.g., a wrong bucket name, etc.).

The log can get quite large, so disable it when you no longer need it.

Bug reports

• https://github.com/edwardspec/mediawiki-aws-s3/issues

See also

• WindowsAzureStorage
• Swift