github.com/mattyw/juju@v0.0.0-20140610034352-732aecd63861/README.md (about)

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