git.oblomov.eu Git - ikiwiki/blob - doc/plugins/amazon_s3.mdwn

   1 [[template id=plugin name=amazon_s3 author="[[Joey]]"]]
   2 [[tag type/special-purpose]]
   3
   4 This plugin allows ikiwiki to publish a wiki in the [Amazon Simple Storage
   5 Service](http://aws.amazon.com/s3) (S3). As pages are rendered, ikiwiki
   6 will upload them to Amazon S3. The entire wiki contents, aside from the
   7 ikiwiki CGI, can then be served directly out of Amazon S3.
   8
   9 You'll need the [[cpan Net::Amazon::S3]] and [[cpan File::MimeInfo]] perl
  10 modules and an Amazon S3 account to use this plugin.
  11
  12 ## configuration
  13
  14 Important note: You should seriously consider turning off `usedirs` before
  15 enabling this plugin. If `usedirs` is enabled, every page has to be stored
  16 in S3 *twice*, as "page/index.html" and as "page/". That will cost you
  17 money and bandwidth.
  18
  19 This plugin uses the following settings in the setup file:
  20
  21 * `amazon_s3_key_id` - Set to your public access key id.
  22 * `amazon_s3_key_file` - Set to the name of a file where you have
  23   stored your secret access key. The content of this file *must*
  24   be kept secret.
  25 * `amazon_s3_bucket` - The globally unique name of the bucket to use to
  26   store the wiki. This determines the URL to your wiki. For example, if you
  27   set it to "foo", then the url will be
  28   "http://foo.s3.amazonaws.com/wiki/".
  29 * `amazon_s3_prefix` - A prefix to prepend to each page name.
  30   The default is "wiki/". Note that due to S3 limitations (lack of support
  31   for uploading a root key), it is not possible to set the prefix to an
  32   empty string.
  33 * `amazon_s3_location` - Optionally, this can be set to control which
  34   datacenter to use. For example, set it to "EU" to for Europe.
  35
  36 Note that you should still set `destdir` in the setup file. The files that
  37 are uploaded to Amazon S3 will still be written to the destdir, too.
  38
  39 Likewise, you will probably want to set the `url` in the setup file.
  40 The url can use the `foo.s3.amazonaws.com` domain name, or another domain
  41 name that is a CNAME for it.
  42
  43 The `hardlink` config file setting is not compatible with this plugin.
  44
  45 ## data transfer notes
  46
  47 If you run 'ikiwiki -setup my.setup' to force a rebuild of your wiki, the
  48 entire thing will be re-uploaded to Amazon S3. This will take time, and
  49 cost you money, so it should be avoided as much as possible.
  50
  51 If you run 'ikiwiki -setup my.setup -refresh', ikiwiki will only upload the
  52 modified pages that it refreshes. Faster and cheaper. Still, if you have
  53 very large pages (for example, a page that inlines hundreds of other pages
  54 .. or is just very large), the complete page contents will be re-uploaded
  55 each time it's changed. Amazon S3 does not currently support partial/rsync
  56 type uploads.
  57
  58 Copy and rename detection is not done, so if you copy or rename a large file,
  59 it will be re-uploaded, rather than copied.