<<TableOfContents>>

== What is it? ==

The goamz package enables [[http://golang.org|Go]] programs to interact with
the [[http://aws.amazon.com/|Amazon Web Services]].

It was developed within Canonical as part of an experiment related to using
the Go language with the [[http://juju.ubuntu.com|juju]] project, but is now
a set of generally adopted and maintained Go packages that talk to several
Amazon Web Services.

The API of AWS is very comprehensive, though, and goamz doesn't even scratch
the surface of it.  That said, it's fairly well tested, and is the foundation
in which further calls can easily be integrated.  We'll continue extending
the API as necessary.

The following packages are available at the moment:

  * gopkg.in/amz.v1/aws
  * gopkg.in/amz.v1/ec2
  * gopkg.in/amz.v1/s3
  * gopkg.in/amz.v1/exp/mturk
  * gopkg.in/amz.v1/exp/sdb
  * gopkg.in/amz.v1/exp/sns

Packages under {{{exp/}}} are still in an experimental or unfinished/unpolished
state.

'''''IMPORTANT:''''' goamz source code was migrated from [[http://launchpad.net/goamz|Launchpad]] to [[http://github.com/go-amz/amz|Github]]. Source on Launchpad is retained for historical reasons. Bugs should be reported on [[http://github.com/go-amz/amz/issues|GitHub]] as well.

== API documentation ==

The API documentation is currently available at:

  * http://godoc.org/gopkg.in/amz.v1

== Example ==

Here is a simple example which connects to AWS and creates an instance (make sure you shut it down afterwards):
{{{
package main

import (
    "gopkg.in/amz.v1/aws"
    "gopkg.in/amz.v1/ec2"
)

func main() {
    auth, err := aws.EnvAuth()
    if err != nil {
        panic(err.Error())
    }
    e := ec2.New(auth, aws.USEast)

    options := ec2.RunInstances{
        ImageId:      "ami-ccf405a5", // Ubuntu Maverick, i386, EBS store
        InstanceType: "t1.micro",
    }
    resp, err := e.RunInstances(&options)
    if err != nil {
        panic(err.Error())
    }

    for _, instance := range resp.Instances {
        println("Now running", instance.InstanceId)
    }
    println("Make sure you terminate instances to stop the cash flow.")
}
}}}

This example will generate the following output:

== Source code ==

To obtain the source code, use [[http://git-scm.com/|Git]] to download projects from [[http://github.com/|GitHub]]:
{{{
$ git clone http://github.com/go-amz/amz.git
}}}

== Reporting bugs ==

Please report bugs on [[http://github.com/go-amz/amz/issues|GitHub]].

== How to build and install goamz ==

Just use "go get" with any of the available packages. For example:
{{{
$ go get gopkg.in/amz.v1/ec2
$ go get gopkg.in/amz.v1/s3
}}}

== Running tests ==

To run tests, first install [[http://gopkg.in/check.v1|gocheck]] with:
{{{
$ go install gopkg.in/check.v1
}}}

Then run go test as usual:
{{{
$ go test gopkg.in/amz.v1/...
}}}

If you want to run integration tests (costs money), set up the EC2 environment variables as usual, and run:
{{{
$ go test -i
}}}

== Mailing list ==

To talk about usage and development of goamz, please join the mailing list:

    http://groups.google.com/group/goamz

== License ==

goamz is licensed under the LGPLv3.