-[[template id=plugin name=amazon_s3 author="[[Joey]]"]]
-[[tag type/special-purpose]]
+[[!template id=plugin name=amazon_s3 author="[[Joey]]"]]
+[[!tag type/special-purpose]]
This plugin allows ikiwiki to publish a wiki in the [Amazon Simple Storage
Service](http://aws.amazon.com/s3) (S3). As pages are rendered, ikiwiki
will upload them to Amazon S3. The entire wiki contents, aside from the
ikiwiki CGI, can then be served directly out of Amazon S3.
-You'll need the [[cpan Net::Amazon::S3]] and [[cpan File::MimeInfo]] perl
+You'll need the [[!cpan Net::Amazon::S3]] and [[!cpan File::MimeInfo]] perl
modules and an Amazon S3 account to use this plugin.
## configuration
-Important note: You should seriously consider turning off `usedirs` before
-enabling this plugin. If `usedirs` is enabled, every page has to be stored
-in S3 *twice*, as "page/index.html" and as "page/". That will cost you
-money and bandwidth.
-
This plugin uses the following settings in the setup file:
* `amazon_s3_key_id` - Set to your public access key id.
set it to "foo", then the url will be
"http://foo.s3.amazonaws.com/wiki/".
* `amazon_s3_prefix` - A prefix to prepend to each page name.
- The default is "wiki/". Note that due to S3 limitations (lack of support
- for uploading a root key), it is not possible to set the prefix to an
- empty string.
+ The default is "wiki/". Note: In order to host your site at the root,
+ it needs to be set to "", and you'll have to
+ [read this](http://aws.typepad.com/aws/2011/02/host-your-static-website-on-amazon-s3.html)
+ for details about configuring your S3 bucket as a website.
* `amazon_s3_location` - Optionally, this can be set to control which
datacenter to use. For example, set it to "EU" to for Europe.
+* `amazon_s3_dupindex` - Normally, when `usedirs` is enabled,
+ "foo/index.html" is stored in S3 as a key named "foo/", and all links
+ between pages use that name. If you also needs links that include
+ "index.html" in their names to work, you can enable this option. Then
+ each index.html file will be stored in S3 *twice*, under both names. This
+ will use more disk and bandwidth, and is not recommended unless you really
+ need it for some reason. These days, it's probably better to configure
+ your S3 bucket as a website.
Note that you should still set `destdir` in the setup file. The files that
are uploaded to Amazon S3 will still be written to the destdir, too.
## data transfer notes
-If you run 'ikiwiki -setup my.setup' to force a rebuild of your wiki, the
+If you run 'ikiwiki --setup my.setup' to force a rebuild of your wiki, the
entire thing will be re-uploaded to Amazon S3. This will take time, and
cost you money, so it should be avoided as much as possible.
-If you run 'ikiwiki -setup my.setup -refresh', ikiwiki will only upload the
+If you run 'ikiwiki --setup my.setup --refresh', ikiwiki will only upload the
modified pages that it refreshes. Faster and cheaper. Still, if you have
very large pages (for example, a page that inlines hundreds of other pages
.. or is just very large), the complete page contents will be re-uploaded
Copy and rename detection is not done, so if you copy or rename a large file,
it will be re-uploaded, rather than copied.
+
+## deleting a bucket
+
+You can use "ikiwiki --setup my.setup --delete-bucket" to delete anything
+that's in the configured bucket, and remove the bucket.