github.com/mhilton/juju-juju@v0.0.0-20150901100907-a94dd2c73455/README.md (about)

     1  juju
     2  ====
     3  
     4  juju is devops distilled.
     5  
     6  Juju enables you to use [Charms](http://juju.ubuntu.com/charms) to deploy your application architectures to EC2, OpenStack,
     7  Azure, HP your data center and even your own Ubuntu based laptop.
     8  Moving between environments is simple giving you the flexibility to switch hosts
     9  whenever you want — for free.
    10  
    11  For more information, see the [docs](https://juju.ubuntu.com/docs/).
    12  
    13  Getting started
    14  ===============
    15  
    16  `juju` is written in Go (http://golang.org), a modern, compiled, statically typed,
    17  concurrent language. This document describes how to build `juju` from source.
    18  
    19  If you are looking for binary releases of `juju`, they are available from the Juju
    20  stable PPA, `https://launchpad.net/~juju/+archive/stable`, and can be installed with:
    21  
    22      sudo apt-add-repository ppa:juju/stable
    23      sudo apt-get update
    24      sudo apt-get install juju
    25  
    26  Setting GOPATH
    27  --------------
    28  
    29  When working with the source of Go programs, you should define a path within
    30  your home directory (or other workspace) which will be your `GOPATH`. `GOPATH`
    31  is similar to Java's `CLASSPATH` or Python's `~/.local`. `GOPATH` is documented
    32  online at `http://golang.org/pkg/go/build/` and inside the `go` tool itself
    33  
    34      go help gopath
    35  
    36  Various conventions exist for naming the location of your `GOPATH`, but it should
    37  exist, and be writable by you. For example
    38  
    39      export GOPATH=${HOME}/work
    40      mkdir $GOPATH
    41  
    42  will define and create `$HOME/work` as your local `GOPATH`. The `go` tool itself
    43  will create three subdirectories inside your `GOPATH` when required; `src`, `pkg`
    44  and `bin`, which hold the source of Go programs, compiled packages and compiled
    45  binaries, respectively.
    46  
    47  Setting `GOPATH` correctly is critical when developing Go programs. Set and
    48  export it as part of your login script.
    49  
    50  Add `$GOPATH/bin` to your `PATH`, so you can run the go programs you install:
    51  
    52      PATH="$GOPATH/bin:$PATH"
    53  
    54  
    55  Getting juju
    56  ============
    57  
    58  The easiest way to get the source for `juju` is to use the `go get` command.
    59  
    60      go get -d -v github.com/juju/juju/...
    61  
    62  This command will checkout the source of `juju` and inspect it for any unmet
    63  Go package dependencies, downloading those as well. `go get` will also build and
    64  install `juju` and its dependencies. To checkout without installing, use the
    65  `-d` flag. More details on the `go get` flags are available using
    66  
    67      go help get
    68  
    69  At this point you will have the git local repository of the `juju` source at
    70  `$GOPATH/github.com/juju/juju`. The source for any dependent packages will
    71  also be available inside `$GOPATH`. You can use `git pull --rebase`, or the 
    72  less convenient `go get -u github.com/juju/juju/...` to update the source
    73  from time to time.
    74  If you want to know more about contributing to `juju`, please read the
    75  [CONTRIBUTING](CONTRIBUTING.md) companion to this file.
    76  
    77  Installing prerequisites
    78  ------------------------
    79  
    80  You can use `make install-dependencies` or, if you prefer to install
    81  them manually, check the Makefile target.
    82  
    83  This will add some PPAs to ensure that you can install the required
    84  golang and mongodb-server versions for precise onwards, in addition to the
    85  other dependencies.
    86  
    87  
    88  Building juju
    89  =============
    90  
    91      go install -v github.com/juju/juju/...
    92  
    93  Will build juju and install the binary commands into `$GOPATH/bin`. It is likely
    94  if you have just completed the previous step to get the `juju` source, the
    95  install process will produce no output, as the final executables are up-to-date.
    96  
    97  If you do see any errors, there is a good chance they are due to changes in
    98  juju's dependencies.  See the
    99  [Dependency management](CONTRIBUTING.md#dependency-management) section of
   100  `CONTRIBUTING` for more information on getting the dependencies right.
   101  
   102  
   103  Using juju
   104  ==========
   105  
   106  After following the steps above you will have the `juju` client installed in
   107  `GOPATH/bin/juju`. You should ensure that this version of `juju` appears earlier
   108  in your path than any packaged versions of `juju`, or older Python juju
   109  commands. You can verify this using
   110  
   111      which juju
   112  
   113  You should be able to bootstrap a local environment now with the following
   114  (Note: the use of sudo for bootstrap here is only required for the local
   115  provider because it uses LXC, which requires root privileges)
   116  
   117      juju init
   118      juju switch local
   119      sudo juju bootstrap
   120  
   121  --upload-tools
   122  --------------
   123  
   124  The `juju` client program, and the juju 'tools' are deployed in lockstep. When a
   125  release of `juju` is made, the compiled tools matching that version of juju
   126  are extracted and uploaded to a known location. This consumes a release version
   127  number, and implies that no tools are available for the next, development, version
   128  of juju. Therefore, when using the development version of juju you will need to
   129  pass an additional flag, `--upload-tools` to instruct the `juju` client to build
   130  a set of tools from source and upload them to the environment as part of the
   131  bootstrap process.
   132  
   133      juju bootstrap -e your-environment --upload-tools {--debug}
   134  
   135  
   136  Installing bash completion for juju
   137  ===================================
   138  
   139      make install-etc
   140  
   141  Will install Bash completion for `juju` cli to `/etc/bash_completion.d/juju`. It does
   142  dynamic completion for commands requiring service, unit or machine names (like e.g.
   143  juju status <service>, juju ssh <instance>, juju terminate-machine <machine#>, etc),
   144  by parsing cached `juju status` output for speedup. It also does command flags
   145  completion by parsing `juju help ...` output.