← Back to branch summary

~nskaggs/+junk/xenial-test

« back to all changes in this revision

Viewing changes to src/github.com/juju/juju/README.md

  • Committer: Nicholas Skaggs
  • Date: 2016-10-24 20:56:05 UTC
  • Revision ID: nicholas.skaggs@canonical.com-20161024205605-z8lta0uvuhtxwzwl
Initi with beta15

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/github.com/juju/juju/README.md
 
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 models is simple giving you the flexibility to switch hosts
 
9
whenever you want — for free.
 
10
 
 
11
For more information, see the [docs](https://jujucharms.com/docs/stable/getting-started).
 
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 model 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 model as part of the
 
131
bootstrap process.
 
132
 
 
133
    juju bootstrap -m your-model --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.