Extension:AWS

From mediawiki.org
Jump to navigation Jump to search
MediaWiki extensions manual
OOjs UI icon advanced-invert.svg
AWS
Release status: stable
Implementation File repository
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.
MediaWiki 1.35+ (master branch)
1.27-1.34 (REL1_34 branch)
PHP 7.3.19+ (master branch)
5.6+ (REL1_34 branch)
Database changes No
Composer edwardspec/mediawiki-aws-s3
License GNU General Public License 2.0 or later
Download

  • $wgAWSCredentials
  • $wgAWSRegion
  • $wgAWSBucketName
  • $wgAWSBucketDomain
  • $wgAWSRepoHashLevels
  • $wgAWSRepoDeletedHashLevels
  • $wgAWSBucketTopSubdirectory

Check usage and version matrix.

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[edit]

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[edit]

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[edit]

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

  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 how to install it.
  5. Create an S3 bucket for images, e.g. wonderfulbali234.
    Note: this name will be seen in 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 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 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.

Installation for older versions of MediaWiki[edit]

See Extension:AWS/Installation for 1.27-1.34. These versions may still receive security fixes (if any), but not new features.

Configuration[edit]

Step 1: configure LocalSettings.php[edit]

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 you anticipate using several hundred buckets, one per wiki, then it's probably better to use one bucket
// with the top level subdirectory as the wiki's name, and permissions properly configured of course.
// While there are no more performance losses by using such a scheme, it might make things messy. Hence, it's
// still a good idea to use one bucket per wiki unless you are approaching your 1,000 bucket per account limit.
$wgAWSBucketTopSubdirectory = "/$wgDBname"; # leading slash is required

Step 2: needed IAM permissions[edit]

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

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>"
        ]
}

Bug reports[edit]

See also[edit]

Footnotes[edit]

  1. Assuming the database (e.g. MySQL) is also not on this server, e.g. in Amazon RDS.
  2. Except in private wikis. For them images are served via img_auth.php . Presigned URLs are not (yet?) supported.