← Back to branch summary

~pjdc/mojo/juju-2-no-fail-when-retrying-errors

« back to all changes in this revision

Viewing changes to docs/mojo/readme.md

  • Committer: Tom Haddon
  • Date: 2015-01-21 07:26:49 UTC
  • mto: This revision was merged to the branch mainline in revision 141.
  • Revision ID: tom.haddon@canonical.com-20150121072649-y61tqnw45yka3gxc
Re-arrange the docs directory so we can have header and footer more easily

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/mojo/readme.md
1
 
     ___           ___         ___          ___     
2
 
    /__/\         /  /\       /  /\        /  /\    
3
 
   |  |::\       /  /::\     /  /:/       /  /::\   
4
 
   |  |:|:\     /  /:/\:\   /__/::\      /  /:/\:\  
5
 
 __|__|:|\:\   /  /:/  \:\  \__\/\:\    /  /:/  \:\ 
6
 
/__/::::| \:\ /__/:/ \__\:\    \  \:\  /__/:/ \__\:\
7
 
\  \:\~~\__\/ \  \:\ /  /:/     \__\:\ \  \:\ /  /:/
8
 
 \  \:\        \  \:\  /:/      /  /:/  \  \:\  /:/ 
9
 
  \  \:\        \  \:\/:/      /__/:/    \  \:\/:/  
10
 
   \  \:\        \  \::/       \__\/      \  \::/   
11
 
    \__\/         \__\/                    \__\/    
 
1
Mojo README
 
2
===========
12
3
 
13
 
   Mojo is a deployment workflow system for Juju.
 
4
Mojo is a deployment workflow system for Juju.
14
5
 
15
6
Mojo is a continuous integration and continuous delivery system for Juju-based
16
7
services managed by Canonical IS. It is intended to replace the current system
26
17
configuration files many deployment permutations can be tested.
27
18
 
28
19
Usage
29
 
=====
 
20
-----
30
21
 
31
22
Mojo provides several commands, each performing one phase of a Juju deployment
32
23
process. These commands reference a Mojo spec for details about the
36
27
working with specs, preparing your deployment, and for integrating with CI
37
28
systems like Jenkins.
38
29
 
39
 
Projects
40
 
--------
 
30
### Projects ###
41
31
 
42
32
A mojo project is the main staging ground for testing. It is directory where 
43
33
deployment artifacts are assembled. A mojo project also has an lxc container
48
38
 
49
39
The root MOJO_DIR is typically /srv/mojo so projects are located:
50
40
 
51
 
/srv/mojo/$MOJO_PROJECT
 
41
    /srv/mojo/$MOJO_PROJECT
52
42
 
53
43
The LOCAL directory is where secrets and certificates or anything that cannot be
54
44
stored in the spec repository should be staged for use by the deployment.
55
45
The mojo secrets phase copies data from the LOCAL directory to the workspace
56
46
local directory.
57
 
/srv/mojo/LOCAL
 
47
 
 
48
    /srv/mojo/LOCAL
58
49
 
59
50
The ROOTFS directory is the lxc container rootfs.
60
 
/srv/mojo/$MOJO_PROJECT/$MOJO_SERIES/ROOTFS
 
51
 
 
52
    /srv/mojo/$MOJO_PROJECT/$MOJO_SERIES/ROOTFS
 
53
 
61
54
with $MOJO_SERIES as either precise, trusty, etc.
62
55
 
63
 
Workspaces
64
 
----------
 
56
### Workspaces ###
65
57
 
66
58
A mojo workspace is staging ground for the specific version of the specification
67
59
being tested. Typically the workspace is named for the revision number of the 
68
60
spec and the stage. i.e 23-production
69
61
 
70
 
/srv/mojo/$MOJO_PROJECT/$MOJO_SERIES/$MOJO_WORKSPACE
 
62
    /srv/mojo/$MOJO_PROJECT/$MOJO_SERIES/$MOJO_WORKSPACE
71
63
 
72
64
Workspace layout:
73
65
 
74
66
The specification is pulled from a bzr repository to the spec directory.
75
67
 
76
 
/srv/mojo/$MOJO_PROJECT/$MOJO_SERIES/$MOJO_WORKSPACE/spec
 
68
    /srv/mojo/$MOJO_PROJECT/$MOJO_SERIES/$MOJO_WORKSPACE/spec
77
69
 
78
70
The build directory is where collect phase stores the charms and payload data
79
71
by default. The build phase script should point to the contents in this
80
72
directory.
81
 
/srv/mojo/$MOJO_PROJECT/$MOJO_SERIES/$MOJO_WORKSPACE/build
 
73
 
 
74
    /srv/mojo/$MOJO_PROJECT/$MOJO_SERIES/$MOJO_WORKSPACE/build
82
75
 
83
76
The charms directory is where the repo phase setups up the charm repository.
84
77
The deploy phase deploys charms from this location.
85
 
/srv/mojo/$MOJO_PROJECT/$MOJO_SERIES/$MOJO_WORKSPACE/charms
 
78
 
 
79
    /srv/mojo/$MOJO_PROJECT/$MOJO_SERIES/$MOJO_WORKSPACE/charms
86
80
 
87
81
The local directory is where secrets and certificates or anything that cannot be
88
82
stored in the spec repository should be moved to for use by the deployment.
89
83
The mojo secrets phase copies data from the LOCAL directory to the workspace
90
84
local directory.
91
 
/srv/mojo/$MOJO_PROJECT/$MOJO_SERIES/$MOJO_WORKSPACE/local
 
85
 
 
86
    /srv/mojo/$MOJO_PROJECT/$MOJO_SERIES/$MOJO_WORKSPACE/local
92
87
 
93
88
 
94
89
Setup Commands
95
 
==============
 
90
--------------
96
91
 
97
92
Create a new project:
98
 
sudo mojo project-new $MOJO_PROJECT -s $MOJO_SERIES
99
 
 eg:
100
 
sudo mojo project-new my-stack-name -s precise
 
93
 
 
94
    sudo mojo project-new $MOJO_PROJECT -s $MOJO_SERIES
 
95
    # eg:
 
96
    sudo mojo project-new my-stack-name -s precise
101
97
 
102
98
 
103
99
List all projects
104
 
mojo project-list
 
100
 
 
101
    mojo project-list
105
102
 
106
103
Delete a project
107
 
sudo mojo project-destroy $MOJO_PROJECT
 
104
 
 
105
    sudo mojo project-destroy $MOJO_PROJECT
108
106
 
109
107
Create a new workspace:
110
 
mojo workspace-new --project $MOJO_PROJECT -s $MOJO_SERIES $SPEC_URL $MOJO_WORKSPACE
111
 
  eg:
112
 
mojo workspace-new --project my-stack-name -s precise lp:~user/mojo-specs/my-stack-name stack-test-wip
 
108
    
 
109
    mojo workspace-new --project $MOJO_PROJECT -s $MOJO_SERIES $SPEC_URL $MOJO_WORKSPACE
 
110
    # eg:
 
111
    mojo workspace-new --project my-stack-name -s precise lp:~user/mojo-specs/my-stack-name stack-test-wip
113
112
 
114
113
List all workspaces
115
 
mojo workspace-list --project $MOJO_PROJECT -s $MOJO_SERIES
116
 
  eg:
117
 
mojo workspace-list --project my-stack-name -s precise
 
114
 
 
115
    mojo workspace-list --project $MOJO_PROJECT -s $MOJO_SERIES
 
116
    # eg:
 
117
    mojo workspace-list --project my-stack-name -s precise
118
118
 
119
119
Delete a workspace
120
 
mojo workspace-destroy --project $MOJO_PROJECT -s $MOJO_SERIES $MOJO_WORKSPACE
121
 
  eg:
122
 
mojo workspace-destroy --project my-stack-name -s precise stack-test-wip
123
120
 
 
121
    mojo workspace-destroy --project $MOJO_PROJECT -s $MOJO_SERIES $MOJO_WORKSPACE
 
122
    # eg:
 
123
    mojo workspace-destroy --project my-stack-name -s precise stack-test-wip
124
124
 
125
125
Phases
126
 
======
 
126
------
 
127
 
127
128
Mojo arranges deployments into several phases in order to ensure their
128
129
repeatability. By breaking a deployment into small parts, Mojo allows you to
129
130
easily build separate staging and production (or any other) environments whose
141
142
 
142
143
 
143
144
Phase Commands
144
 
==============
 
145
--------------
145
146
 
146
 
mojo run
147
 
--------
 
147
### mojo run ###
148
148
 
149
149
The one command to rule them all. The mojo run command pulls down the spec url, 
150
150
reads the manifest and begins executing each phase in order per the manifest.
151
151
 
152
 
mojo run --project $MOJO_PROJECT --series $MOJO_SERIES --stage $MOJO_STAGE $SPEC_URL $MOJO_WORKSPACE
153
 
  eg:
154
 
mojo run --project my-stack-name --series precise --stage devel lp:~user/mojo-specs/my-stack-name stack-test-wip
155
 
 
156
 
 
157
 
mojo secrets
158
 
------------
 
152
    mojo run --project $MOJO_PROJECT --series $MOJO_SERIES --stage $MOJO_STAGE $SPEC_URL $MOJO_WORKSPACE
 
153
    # eg:
 
154
    mojo run --project my-stack-name --series precise --stage devel lp:~user/mojo-specs/my-stack-name stack-test-wip
 
155
 
 
156
 
 
157
### mojo secrets ###
 
158
 
159
159
The secrets phase copies secrets files from a staging directory (Default:
160
160
/srv/mojo/LOCAL/$MOJO_PROJECT/$MOJO_STAGE) to the workspace local directory
161
161
(/srv/mojo/LOCAL/$MOJO_PROJECT/$MOJO_STAGE) where they can be accessed by the
162
162
remaining phases.
163
163
 
164
 
Options: 
165
 
  config=STAGED_SECRETS_DIRECTORY
166
 
    Directory where secrets are staged
167
 
    Default: /srv/mojo/LOCAL/$MOJO_PROJECT/$MOJO_STAGE
168
 
 
169
 
 
170
 
mojo collect
171
 
------------
 
164
> Options: 
 
165
>   config=STAGED_SECRETS_DIRECTORY
 
166
>     Directory where secrets are staged
 
167
>     Default: /srv/mojo/LOCAL/$MOJO_PROJECT/$MOJO_STAGE
 
168
 
 
169
 
 
170
### mojo collect ###
 
171
 
172
172
The collect phase gathers all code and other resources required to build your
173
173
service via codetree. Some services may be composed only of charms, while others
174
174
may collect static content, local configuration, or code that must be compiled.
177
177
format is the following where destination is relative to
178
178
$MOJO_WORKSPACE_DIR/build and source is a remote resource or a local directory.
179
179
Example:
180
 
destination             source1
181
 
../spec/destination     source2
182
 
 
183
 
Options: 
184
 
  config=COLLECT_CONFIG_FILENAME
185
 
    The name of the codetree collect configuration file
186
 
 
187
 
 
188
 
mojo builddeps
189
 
--------------
 
180
 
 
181
> destination             source1
 
182
> ../spec/destination     source2
 
183
 
 
184
> Options: 
 
185
>   config=COLLECT_CONFIG_FILENAME
 
186
>     The name of the codetree collect configuration file
 
187
 
 
188
 
 
189
### mojo builddeps ###
 
190
 
190
191
The builddeps phase prepares the lxc container by installing any required
191
192
packages, apt repositories or apt repository gpg keys. It is passed the package,
192
193
repos or repo_keys options using a comma delimited list.
193
194
 
194
 
Options: 
195
 
  repo_keys=APT_GPG_KEY[,APT_GPG_KEY]
196
 
    Comma delimited list of apt repository GPG key file names
197
 
  repos=REPO[,REPO]
198
 
    Comma delimited list of apt repositories (See man apt-add-repository)
199
 
  packages=PACKAGE_NAME[,PACKAGE_NAME]
200
 
    Comma delimited list of packages.
201
 
 
202
 
 
203
 
mojo script
204
 
-----------
 
195
> Options: 
 
196
>   repo_keys=APT_GPG_KEY[,APT_GPG_KEY]
 
197
>     Comma delimited list of apt repository GPG key file names
 
198
>   repos=REPO[,REPO]
 
199
>     Comma delimited list of apt repositories (See man apt-add-repository)
 
200
>   packages=PACKAGE_NAME[,PACKAGE_NAME]
 
201
>     Comma delimited list of packages.
 
202
 
 
203
 
 
204
### mojo script ###
 
205
 
205
206
A script phase simply executes a user-defined script. Use scripts to manipulate
206
207
your Juju units directly or to set up external resources.
207
208
 
214
215
 
215
216
Environment variables are injected into the script environment (Build and verify
216
217
are subclasses of script and get these too).
 
218
 
217
219
    MOJO_PROJECT = Mojo project name
218
220
    MOJO_WORKSPACE = Workspace name
219
221
    MOJO_WORKSPACE_DIR = Workspace path
224
226
    MOJO_LOCAL_DIR = Workspace local dir
225
227
    MOJO_STAGE = Stage 
226
228
 
227
 
Options: 
228
 
  config=SCRIPT_NAME 
229
 
    The name of the script to be executed
230
 
  lxc=True/False
231
 
    Whether to execute the script inside the lxc container
232
 
    Defaults to False, except for the build phase which forces
233
 
    lxc=True.
234
 
  KEY=VALUE
235
 
    All KEY=VALUE paramaters will be set as environment variables for use
236
 
    by the script
237
 
 
238
 
 
239
 
mojo build
240
 
----------
 
229
> Options: 
 
230
>   config=SCRIPT_NAME 
 
231
>     The name of the script to be executed
 
232
>   lxc=True/False
 
233
>     Whether to execute the script inside the lxc container
 
234
>     Defaults to False, except for the build phase which forces
 
235
>     lxc=True.
 
236
>   KEY=VALUE
 
237
>     All KEY=VALUE paramaters will be set as environment variables for use
 
238
>     by the script
 
239
 
 
240
### mojo build ###
 
241
 
241
242
A build phase is nearly identical to a script phase, except that network access
242
243
in the lxc container is prohibited during execution. This ensures that all 
243
244
required resources are documented and available during collect.