MediaWiki extensions manual

AWS Release status: stableCategory:Stable extensions
Implementation	File repositoryCategory:File repository extensions
Description	Stores MediaWiki images in Amazon S3
Author(s)	Edward Chernenkotalk
Latest version	0.11.1 (2020-12-15)
Compatibility policy	Master maintains backward compatibility.Category:Extensions with master compatibility policy
MediaWiki	1.35+ (master branch) 1.27-1.34 (REL1_34 branch)Category:Extensions with manual MediaWiki version
PHP	7.3.19+ (master branch) 5.6+ (REL1_34 branch)
Database changes	No
Composer	edwardspec/mediawiki-aws-s3Category:Extensions supporting Composer
License	GNU General Public License 2.0 or later
Download	GitHub: project page git repository URL [help ] commit history Note: No localisation updates are provided by translatewiki.net . Category:Extensions in GitHub version control
Parameters $wgAWSCredentials $wgAWSRegion $wgAWSBucketName $wgAWSBucketDomain $wgAWSRepoHashLevels $wgAWSRepoDeletedHashLevels $wgAWSBucketTopSubdirectory
Hooks used MediaWikiServices Category:MediaWikiServices extensions

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 doesn't contain any important data^[1] and can be created/destroyed by Autoscaling.
2. Visitors download images directly from Amazon S3^[2] (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's 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 don't have Composer installed, see Composer for instructions on installing it.
5. Create an S3 bucket for images, e.g. wonderfulbali234.

   Note: this name will be seen in the URL of images.

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 doesn't have an IAM profile, obtain a key/secret for AWS API. You'll 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

wfLoadExtension( 'AWS' );

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

$wgAWSRegion = 'us-east-1'; # Northern Virginia

// Replace <something> with the name of your S3 bucket, e.g. wonderfulbali234.
$wgAWSBucketName = "<something>";

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

{
        "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 can help you notice some misconfigurations (wrong bucket name, etc.).

The log can be quite large, so it should be disabled when you don't need it anymore.

Bug reports

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

See also

• WindowsAzureStorage
• Swift

Footnotes

This extension is included in the following wiki farms/hosts and/or packages: Canasta Category:Extensions included in Canasta ProWikiCategory:Extensions included in ProWiki TelepediaCategory:Extensions included in Telepedia WikiForgeCategory:Extensions included in WikiForge This is not an authoritative list. Some wiki farms/hosts and/or packages may contain this extension even if they are not listed here. Always check with your wiki farms/hosts or bundle to confirm.