1
=== modified file 'htmldocs/authors-charm-writing.html'
2
--- htmldocs/authors-charm-writing.html	2013-07-15 13:01:43 +0000
3
+++ htmldocs/authors-charm-writing.html	2013-07-25 01:29:31 +0000
4
@@ -83,8 +83,9 @@
5
83
            </ul>
83
            </ul>
6
84
            <h1>Charm Authors</h1>
84
            <h1>Charm Authors</h1>
7
85
            <ul></ul>
85
            <ul></ul>
8
86
            <li class=""><a href="authors-charm-intro.html">Want to write a charm?</a></li>
9
86
            <li class=""><a href="authors-charm-anatomy.html">Anatomy of a charm</a></li>
87
            <li class=""><a href="authors-charm-anatomy.html">Anatomy of a charm</a></li>
11
87
            <li class=""><a href="authors-charm-writing.html">Writing a charm</a></li>
88
            <li class=""><a href="authors-charm-writing.html">Writing a Charm</a></li>
12
88
            <li class=" sub"><a href="authors-subordinate-services.html">Subordinate services</a></li>
89
            <li class=" sub"><a href="authors-subordinate-services.html">Subordinate services</a></li>
13
89
            <li class=" sub"><a href="authors-implicit-relations.html">Implicit Relations</a></li>
90
            <li class=" sub"><a href="authors-implicit-relations.html">Implicit Relations</a></li>
14
90
            <li class=" sub"><a href="authors-testing.html">Charm Testing</a></li>
91
            <li class=" sub"><a href="authors-testing.html">Charm Testing</a></li>
15
@@ -104,343 +105,267 @@
16
104
        </div>
105
        </div>
17
105
        <div class="grid-9 doc-content">
106
        <div class="grid-9 doc-content">
18
106
          <article>
107
          <article>
356
107
            <section id ="charm-writing">
108
<h1>Your First charm starts here!</h1>
357
108
            <h1>Writing a charm</h1>
109
<p>Okay, so you have read up all the background info on what a charm is, how it works, and what parts of the charm do what, now it is time to dust off your favourite code editor (no arguments please) and get charming!</p>
358
109
            <p>This tutorial demonstrates the basic workflow for writing, running and debugging a juju charm. Charms are a way to package and share your service deployment and orchestration knowledge and share them with the world.</p>
110
<p>For this example, we are imagining that we want to create a charm for <a href="http://vanillaforums.org/" >the Vanilla forum software</a></p>
359
110
            
111
360
111
            <h2>Creating the charm</h2>
112
<span class="number"> 1 </span>
361
112
            <p>In this example we are going to write a charm to deploy the drupal CMS system. For the sake of simplicity, we are going to use the mysql charm that comes bundled with juju. Assuming the current directory is the juju trunk, let's enter the directory</p>
113
          <div class="step" id="step01">
362
113
            
114
          <h2>Prepare yourself</h2>
363
114
            <h3>Creating a README File</h3>
115
          <p>As we are writing a charm, it makes sense to create it in a local charm repository (see how to deploy from a local repository <a href="./charms-deploying.html" target="#local">here</a>) to make it easy to test in your Juju environment.</p>
364
115
            <p>First create a README file with your text editor. This file must be plain text,the Charm Store will parse Markdown format and display it on the Charm Store's web interface, so it will be the public facing page for your charm. We recommend you leave basic usage instructions on how to use your charm in the README.</p>
116
          <p>Go to your home directory (or wherever is appropriate and make the appropriate file structure:</p>
365
116
            
117
          <pre>cd ~<br>mkdir -p charms/precise/vanilla </pre>
366
117
            <h3>Making the metadata</h3>
118
          
367
118
            <p>Now let's make the metadata and hooks directory:</p>
119
          </div>
368
119
            <pre><code>
120
369
120
            mkdir -p drupal/hooks
121
<span class="number" > 2 </span>
370
121
            vim drupal/metadata.yaml
122
          <div class="step" id="step02">
371
122
            </code></pre>
123
          <h2>Create the README file</h2>
372
123
            <p>Edit the metadata.yaml file to resemble:</p>
124
          <p>Fire up your text editor and create a readme file.</p>
373
124
            <pre><code>
125
          <p>This step is especially important if you intend making your charm public, but it is very useful even if your charm will only ever be seen by you. The README is a good place to make nots about how the charm works, what information it expects to communicate and how.</p>
374
125
            name: drupal
126
          <p>Although a plain text file is fine, you can also write your README file using Markdown (in which case use the .md suffix). The advantage of this, other than it looks quite neat, is that the Charm Store will render Mardown properly online, so your README will look and read better.</p>
375
126
            summary: "Drupal CMS"
127
          <p>Here is a quick example README file for our Vanilla charm:</p>
376
127
            maintainer: "Drupal PowerUser &lt;drupaluser@somedomain.foo&gt;"</p>
128
          <pre class="prettyprint lang-yaml">
377
128
            description: Installs the drupal CMS system, relates to the mysql charm provided in examples directory. Can be scaled to multiple web servers
129
# Overview
378
129
            &nbsp;requires:
130
379
130
            &nbsp;&nbsp;&nbsp;db
131
Vanilla is a powerful open source web-based forum. This charm will deploy the forum software and connect it to a running MySQL database. This charm will install the Vanilla files in /var/www/vanilla/
380
131
            &nbsp;interface: 
132
381
132
            &nbsp;&nbsp;&nbsp;mysql
133
# Installation
382
133
            </code></pre>
134
383
134
            
135
To deploy this charm you will need at a minimum: a cloud environment, working Juju installation and a successful bootstrap. Once bootstrapped, deploy the MySQL charm and then this Vanilla charm:
384
135
            <p>The metadata.yaml file provides metadata around the charm. The file declares a charm with the name drupal. Since this is the first time to edit this charm, its revision number is one. A short and long description of the charm are provided. The final field is <cite>requires</cite>, this mentions the interface type required by this charm. Since this drupal charm uses the services of a mysql database, we need to require it in the metadata. Since this charm does not provide a service to any other charm, there is no <cite>provides</cite> field. You might be wondering where did the interface name &quot;mysql&quot; come from, you can locate the interface information from the mysql charm's metadata.yaml.  Here it is for convenience:</p>
136
385
136
            <pre><code>
137
    juju deploy mysql
386
137
            name: mysql
138
    juju deploy vanilla
387
138
            summary: "MySQL relational database provider"
139
388
139
            maintainer: "Joe Charmer &lt;youremail@whatever.com&gt;"
140
Add a relation between the two of them:
389
140
            description: |
141
390
141
            &nbsp;&nbsp;&nbsp;&nbsp;Installs and configures the MySQL package (mysqldb), then runs it.
142
    juju add-relation mysql vanilla
391
142
             
143
392
143
            &nbsp;&nbsp;&nbsp;Upon a consuming service establishing a relation, creates a new
144
And finally expose the Vanilla service:
393
144
            &nbsp;&nbsp;&nbsp;database for that service, if the database does not yet
145
394
145
            &nbsp;&nbsp;&nbsp;exist. Publishes the following relation settings for consuming
146
    juju expose vanilla</pre>
395
146
            &nbsp;&nbsp;&nbsp;services:
147
396
147
             
148
          <p>Obviously, you can include any useful info you wish.</p>
397
148
            &nbsp;&nbsp;database: database name
149
          </div>
398
149
            &nbsp;&nbsp;&nbsp;&nbsp;user: user name to access database
150
          
399
150
            &nbsp;&nbsp;&nbsp;&nbsp;password: password to access the database
151
<span class="number" > 3 </span>
400
151
            &nbsp;&nbsp;&nbsp;&nbsp;host: local hostname
152
          <div class="step" id="step03">
401
152
            provides:
153
          <h2>Make some metadata.yaml</h2>
402
153
            &nbsp;&nbsp;&nbsp;db:
154
          <p>The <strong>metadata.yaml</strong> file is really important. This is the file that Juju reads to find out what a charm is, what it does and what it needs to do it.</p>
403
154
            &nbsp;&nbsp;&nbsp;&nbsp;interface: mysql</p>
155
          <p>The yaml syntax is at once simple, but exact, so if you have any future problems with Juju not recognising your charm, this is the first port of call! the information is stored in simple <span class="pre">&LT;key&GT; : &LT;value&GT;</span> associations. The first four are pretty self explanitory:</p>
404
155
            </code></pre>
156
          <pre class="prettyprint lang-basic">
405
156
            
157
name: vanilla
406
157
            <p>That very last line mentions that the interface that mysql provides to us is &quot;mysql&quot;. Also the description mentions that four parameters are sent to the connecting charm (database, user, password, host) in order to enable it to connect to the database. We will make use of those variables once we start writing hooks. Such interface information is either provided in a bundled README file, or in the description. You can also read the charm code to discover such information as well.</p>
158
summary: Vanilla is an open-source, pluggable, multi-lingual forum.
407
158
            <p>In the next steps we will write the necessary hook scripts.</p>
159
maintainer: Your Name &lt;your@email.tld&gt;
408
159
            
160
description: |
409
160
            <h2>Have a plan</h2>
161
  Vanilla is designed to deploy and grow small communities to scale. 
410
161
            <p>When attempting to write a charm, it is beneficial to have a mental plan of what it takes to deploy the software. In our case, you should deploy drupal manually, understand where its configuration information is written, how the first node is deployed, and how further nodes are configured. With respect to this charm, this is the plan:</p>
162
  This charm deploys Vanilla Forums as outlined by the Vanilla Forums
411
162
            
163
  installation guide.
412
163
            <ul>
164
</pre>
413
164
            <li>Install hook installs all needed components (apache, php, drush)</li>
165
          <p>The summary should be a brief description of the service being deployed, whereas the description can go into more detail.</p>
414
165
            <li>Once the database connection information is ready, call drush on first node to perform the initial setup (creates DB tables, completes setup)</li>
166
          <p>The next value to define is the category. This is primarily for organising the charm in the charm store. the available categories are:</p>
415
166
            <li>For scaling onto other nodes, the DB tables have already been set-up. Thus we only need to append the database connection information into drupal's settings.php file. We will use a template file for that</li>
167
          <ul>
416
167
            </ul>
168
          <li><strong>databases -</strong> MySQL, Postgres, couchDB, etc.</li>
417
168
            
169
          <li><strong>file-servers - </strong>storage apps such as ceph</li>
418
169
            
170
          <li><strong>applications -</strong>applications like mediawiki, wordpress</li>
419
170
            <p class="note"><strong>Note:</strong>The hooks in a charm are executable files that can be written using any scripting or programming language. In our case, we'll use bash</p>
171
          <li><strong>cache-proxy - </strong>services such as haproxy and Varnish.</li>
420
171
            
172
          <li><strong>app-servers - </strong>infrastructure services like Apache and Tomcat</li>
421
172
            <p>For production charms it is always recommended that you install software components from the Ubuntu archive (using apt-get) in order to get security updates. However in this example I am installing drush (Drupal shell) using apt-get, then using that to download and install the latest version of drupal. If you were deploying your own code, you could just as easily install a revision control tool (bzr, git, hg...etc) and use that to checkout a code branch to deploy from. This demonstrates the flexibility offered by juju which doesn't really force you into one way of doing things.</p>
173
          <li><strong>miscellaneous - </strong>anything which doesn't neatly fit anywhere above.</li>
422
173
            
174
          </ul>
423
174
            
175
          <p>Your charm can belong to more than one category, though in almost all cases it should be in just one. Because there could be more than one entry here, the yaml is formatted as a list:</p>
424
175
            <h2>Write hooks</h2>
176
          <pre class="prettyprint lang-yaml">categories:<br>  - applications</pre>
425
176
            <p>Let's change into the hooks directory:</p>
177
          <p>Next we need to explain which services are actually provided by this service. This is done using an indent for each service provided, followed by a description of the interface. The interface name is important as it can be used elsewhere in the environment to relate back to this charm, e.g. when writing hooks.</p>
426
177
            <pre>
178
          <p>Our Vanilla charm is a web-based service which exposes a simple http interface:</p> 
427
178
            cd drupal/hooks
179
          <pre class="prettyprint lang-yaml">provides:<br>  website:<br>    interface: http</pre>
428
179
            vim install
180
          <p>The name given here is important as it will be used in hooks that we write later, and the interface name will be used by other charms which may want to relate to this one.</p>
429
180
            </pre>
181
          <p>Similarly we also need to provide a "requires" section. In this case we need a database. Checking out the metadata of the MySQL charm we can see that it provides this via the interface name "mysql", so we can use this name in our metadata.</p>
430
181
            
182
          <p>The final file should look like this:</p>
431
182
            <p>Since you should have already installed drupal, you have an idea what it takes to get it installed. My install script looks like:</p>
183
          <pre class="prettyprint lang-yaml">
432
183
            <pre><code>#!/bin/bash
184
name: vanilla
433
184
            set -eux # -x for verbose logging to juju debug-log
185
summary: Vanilla is an open-source, pluggable, themeable, multi-lingual forum.
434
185
            juju-log "Installing drush,apache2,php via apt-get"
186
maintainer: Your Name &lt;your@email.tld&gt;
435
186
            apt-get -y install drush apache2 php5-gd libapache2-mod-php5 php5-cgi mysql-client-core-5.5
187
description: |
436
187
            a2enmod php5
188
  Vanilla is designed to deploy and grow small communities to scale. 
437
188
            /etc/init.d/apache2 restart
189
  This charm deploys Vanilla Forums as outlined by the Vanilla Forums installation guide.
438
189
            juju-log "Using drush to download latest Drupal"
190
categories:
439
190
            # Typo on next line, it should be www not ww
191
  - applications
440
191
            cd /var/ww &amp;&amp; drush dl drupal --drupal-project-rename=juju
192
provides:
441
192
            </code></pre>
193
  website:
442
193
            
194
    interface: http
443
194
            <p>I have introduced an artificial typo on the last line &quot;ww not www&quot;, this is to simulate any error which you are bound to face sooner or later. Let's create other hooks:</p>
195
requires:
444
195
            <pre>
196
  database:
445
196
            vim start
197
    interface: mysql</pre>
446
197
            </pre>
198
          <p>
447
198
            
199
          <p>For some charms you will want a "peers" section also. This follows the same format, and its used for optional connections, such as you might use for interconnecting services in a cluster
448
199
            <p>The start hook is empty, however it needs to be a valid executable, thus we'll add the first bash shebang line, here it is:</p>
200
          </p>
449
200
            <pre>
201
          
450
201
            <span class="c">#!/bin/bash</span>
202
451
202
            </pre>
203
          </div>         
452
203
            
204
<span class="number" > 4 </span>
453
204
            <p>Here's the &quot;stop&quot; script:</p>
205
          <div class="step" id="step04">
454
205
            <pre>
206
          <h2>Writing hooks</h2>
455
206
            #!/bin/bash
207
          <p>As you will know from your through reading of <a href="./authors-charm-anatomy.html"> the anatomy of a charm</a> The hooks are the important scripts that actually do things. You can write hooks in whatever language you can reasonably expect to execute on an Ubuntu server</p>
456
207
            juju-log "Stopping apache"
208
          <p>For our charm, the hooks we will need to create are:</p>
457
208
            /etc/init.d/apache2 stop
209
          <ul>
458
209
            </pre>
210
          <li>start - for when the service needs to be started.</li>
459
210
            
211
          <li>stop - for stopping it again.</li></ul>
460
211
            <p>The final script, which does most of the work is &quot;db-relation-changed&quot;. This script gets the database connection information set by the mysql charm then sets up drupal for the first time, and opens port 80 for web access. Let's start with a simple version that only installs drupal on the first node. Here it is:</p>
212
          <li>install - for actually fetching and installing the Vanilla code.</li>
461
212
            <pre>#!/bin/bash
213
          <li>database-relation-changed - this will run when we connect (or re-connect, or disconnect) our service to the MySQL database. This hook will need to manage this connection.</li>
462
213
            set -eux # -x for verbose logging to juju debug-log
214
          <li>website-relation-joined - this will run when/if a service connects to our charm.</li>
463
214
            hooksdir=$PWD
215
          </ul>
464
215
            user=`relation-get user`
216
          <p>So first up we should create the hooks directory, and start creating our first hook:</p>
465
216
            password=`relation-get password`
217
          <pre>mkdir hooks<br>cd hooks<br>vi start</pre>
466
217
            host=`relation-get host`
218
          <p>(Use your favourite editor, naturally - no flames please)</p>
467
218
            database=`relation-get database`
219
          <p>We have started with the start hook, because it is pretty simple. Our charm will be served up by apache, so all we need to do to start the service is make sure apache is running:</p>
468
219
            # All values are set together, so checking on a single value is enough
220
          <pre class="prettyprint lang-bash">#!/bin/bash<br>set -e<br>service apache2 restart</pre>
469
220
            # If $user is not set, DB is still setting itself up, we exit awaiting next run
221
          <p>A bit of explanation for this one. As we are writing in bash, and we need the files to be executable, we start with a hash-bang line indicating this is a bash file.
470
221
            [ -z "$user" ] &amp;&amp; exit 0
222
          the <span class="pre">set -e</span> line means that if any subsequent command returns false (non-zero) the script will stop and raise an error - this is important so that Juju can work out if things are running properly.
471
222
            juju-log "Setting up Drupal for the first time"
223
          </p>
472
223
            cd /var/www/juju &amp;&amp; drush site-install -y standard \
224
          <p>The final line starts the apache webservice, thus also starting our Vanilla service. Why do we call 'restart'? One of the important ideas behind hooks is that they should be 'idempotent'. That means that the opration should be capable of being run many times without changing the intended result (basically). in this case, we don't want an error if apache is actually already running, we just want it to run and reload any config changes.</p>
473
224
            --db-url=mysql://$user:$password@$host/$database \
225
          <p>Once you have saved the file, it is important to make sure that you set it to be executable too!</p>
474
225
            --site-name=juju --clean-url=0
226
          <pre>chmod +x start</pre>
475
226
            cd /var/www/juju &amp;&amp; chown www-data sites/default/settings.php
227
          <p>With the easy bit out of the way, how about the install hook? This needs to install any dependencies, fetch the actual software and do any other config and service jobs that need to happen. here is an example for our vanilla charm:</p>
476
227
            open-port 80/tcp
228
                    
477
228
            </code>
229
<pre class="prettyprint">
478
229
            </pre>
230
#!/bin/bash
479
230
            
231
480
231
            <p>The script is quite simple, it reads the four variables needed to connect to mysql, ensures they are not null, then passes them to the drupal installer. Make sure all the hook scripts have executable permissions, and change directory above the examples directory:</p>
232
set -e # If any command fails, stop execution of the hook with that error
481
232
            <pre>chmod +x *
233
482
233
            $ cd ../../../..
234
apt-get install -y apache2 php5-cgi php5-mysql curl php5-gd wget libapache2-mod-php5
483
234
            </pre>
235
484
235
            
236
dl="https://github.com/vanillaforums/Garden/archive/Vanilla_2.0.18.8.tar.gz"
485
236
            <p>Checking on the drupal charm file-structure, this is what we have:</p>
237
486
237
            <pre>
238
# Grab Vanilla from upstream.
487
238
            find examples/precise/drupal
239
juju-log "Fetching $dl"
488
239
            examples/precise/drupal
240
wget "$dl" -O /tmp/vanilla.tar.gz
489
240
            examples/precise/drupal/metadata.yaml
241
490
241
            examples/precise/drupal/hooks
242
# IDEMPOTENCY is very important in all charm hooks, even the install hook.
491
242
            examples/precise/drupal/hooks/db-relation-changed
243
if [ -f /var/www/vanilla/conf/config.php ]; then
492
243
            examples/precise/drupal/hooks/stop
244
  cp /var/www/vanilla/conf/config.php /tmp/
493
244
            examples/precise/drupal/hooks/install
245
  rm -rf /var/www/vanilla
494
245
            examples/precise/drupal/hooks/start
246
fi
495
246
            </pre>
247
496
247
            
248
# Extract to a known location
497
248
            <h2>Test run</h2>
249
juju-log "Extracting Vanilla"
498
249
            <p>Let us deploy the drupal charm. Remember that the install hook has a problem and will not exit cleanly. Deploying:</p>
250
tar -xvzf /tmp/vanilla.tar.gz -C /var/www/
499
250
            
251
mv /var/www/Garden-Vanilla* /var/www/vanilla
500
251
            <pre>juju bootstrap</pre>
252
501
252
            
253
if [ -f /tmp/config.php ]; then
502
253
            <p>Wait a minute for the environment to bootstrap. Keep issuing the status command till you know the environment is ready:</p>
254
  mv /tmp/config.php /var/www/vanilla/conf/
503
254
            
255
fi
504
255
            <pre>
256
505
256
            juju status
257
chmod -R 777 /var/www/vanilla/conf /var/www/vanilla/uploads /var/www/vanilla/cache
506
257
            2011-06-07 14:04:06,816 INFO Connecting to environment.
258
507
258
            machines:
259
juju-log "Creating apache2 configuration"
508
259
            &nbsp;0:
260
cat &lt;&lt;EOF $gt; /etc/apache2/sites-available/vanilla
509
260
            &nbsp;&nbsp;&nbsp;agent-state: running
261
&lt;VirtualHost *:80&gt;
510
261
            &nbsp;&nbsp;&nbsp;dns-name: ec2-50-16-107-102.compute-1.amazonaws.com
262
  ServerAdmin webmaster@localhost
511
262
            &nbsp;&nbsp;&nbsp;instance-id: i-130c9168
263
  DocumentRoot /var/www/vanilla
512
263
            &nbsp;&nbsp;&nbsp;instance-state: running
264
  
513
264
            services:
265
  &lt;Directory /var/www/vanilla&gt;
514
265
            2011-06-07 14:04:11,125 INFO 'status' command finished successfully
266
    Options Indexes FollowSymLinks MultiViews
515
266
            </pre>
267
    AllowOverride All
516
267
            
268
    Order allow,deny
517
268
            <p>It can be beneficial when debugging a new charm to always have the distributed debug-log running in a separate window:</p>
269
    allow from all
518
269
            <pre>juju debug-log</pre>
270
  &lt;/Directory&gt;
519
270
            <p>Let's deploy the mysql and drupal charms:</p>
271
520
271
            <pre>juju deploy --repository=examples local:precise/mysql
272
  ErrorLog \${APACHE_LOG_DIR}/vanilla.log
521
272
            juju deploy --repository=examples local:precise/drupal</pre>
273
  LogLevel warn
522
273
            
274
523
274
            <p>This deploy is telling juju to look in a local repository for our charm, specifically in the examples/precise/mysql and examples/precise/drupal folders. Local repositories specified with the --repository switch must point to a directory which contains sub-directories named after an Ubuntu series (e.g. precise) and the charms. The repository can be named anything you wish.</p>
275
  CustomLog \${APACHE_LOG_DIR}/access.log combined
524
275
            <p>Thus, when creating charms locally, this syntax should be followed:</p>
276
&lt;/VirtualHost&gt;
525
276
            <pre><code>
277
EOF
526
277
            repositoryName/ubuntuReleaseName/charmName</code></pre>
278
527
278
            <p>Once the machines are started (hint: check the debug-log), issue a status command:</p>
279
a2dissite 000-default
528
279
            <pre>juju status
280
a2ensite vanilla
529
280
            
281
530
281
            <p>machines:
282
service apache2 reload
531
282
            &nbsp;0:
283
532
283
            &nbsp;&nbsp;&nbsp;agent-state: running
284
juju-log "Files extracted, waiting for other events before we do anything else!"
533
284
            &nbsp;&nbsp;&nbsp;dns-name: ec2-50-16-107-102.compute-1.amazonaws.com
285
</pre>
534
285
            &nbsp;&nbsp;&nbsp;instance-id: i-130c9168
286
          <p>We aren't going to go for a line-by-line explanation of that, but there are a few things worth noting</p>
535
286
            &nbsp;&nbsp;&nbsp;instance-state: running</p>
287
          <p>Firstly, note the use of the -y option of the apt-get command. this assumes a 'yes' answer to any questions and removes any manual install options (e.g. services that run config dialogs when they install</p>
536
287
            &nbsp;1:
288
          <p>In our script, we are fetching the tarball of the Vanilla software. In these cases, it is obviously always better to point to a specific, permanent link to a version of the software. </p>         
537
288
            &nbsp;&nbsp;&nbsp;agent-state: running
289
          <p>Also, you will notice that we have used the <span class="pre">juju-log</span> command. This basically spits messages out into the juju log, which is very useful for testing and debugging. We will cover that in more detail later in this walkthrough. </p>
538
289
            &nbsp;&nbsp;&nbsp;dns-name: ec2-50-19-24-186.compute-1.amazonaws.com
290
          <p>The next step is to create the relationship hooks... </p>
539
290
            &nbsp;&nbsp;&nbsp;instance-id: i-17079a6c
291
          <p>We know from our metadata that we have a connection called 'database', so we can have hooks that relate to that. Note that we don't have to create hooks for all possible events if they are not required - if Juju doesn't find a hook file for a paticular action, it just assumes everything is okay and carries on. It is up to you to decide which events require a hook.</p>
540
291
            &nbsp;&nbsp;&nbsp;instance-state: running
292
          <p>Let's take a stab at the 'database-relation-changed' hook:</p>
541
292
            &nbsp;2:
293
          <pre class="prettyprint">#!/bin/bash
542
293
            &nbsp;&nbsp;&nbsp;agent-state: running
294
543
294
            &nbsp;&nbsp;&nbsp;dns-name: ec2-23-20-194-198.compute-1.amazonaws.com
295
set -e # If any command fails, stop execution of the hook with that error
544
295
            &nbsp;&nbsp;&nbsp;instance-id: i-d7079aac
296
545
296
            &nbsp;&nbsp;&nbsp;instance-state: running
297
db_user=`relation-get user`
546
297
            services:
298
db_db=`relation-get database`
547
298
            &nbsp;mysql:
299
db_pass=`relation-get password`
548
299
            &nbsp;&nbsp;&nbsp;charm: cs:precise/mysql-3
300
db_host=`relation-get private-address`
549
300
            &nbsp;&nbsp;&nbsp;relations: {}
301
550
301
            &nbsp;&nbsp;&nbsp;units:
302
if [ -z "$db_db" ]; then
551
302
            &nbsp;&nbsp;&nbsp;mysql/0:
303
  juju-log "No database information sent yet. Silently exiting"
552
303
            &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;agent-state: started
304
  exit 0
553
304
            &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;machine: 2
305
fi
554
305
            &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;public-address: ec2-23-20-194-198.compute-1.amazonaws.com
306
555
306
            &nbsp;drupal:
307
vanilla_config="/var/www/vanilla/conf/config.php"
556
307
            &nbsp;&nbsp;&nbsp;charm: local:precise/drupal-3
308
557
308
            &nbsp;&nbsp;&nbsp;relations: {}
309
cat <<EOF > $vanilla_config
558
309
            &nbsp;&nbsp;&nbsp;units:
310
&LT;?php if (!defined('APPLICATION')) exit();
559
310
            &nbsp;&nbsp;&nbsp;drupal/0:
311
560
311
            &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;agent-state: install-error
312
\$Configuration['Database']['Host'] = '$db_host';
561
312
            &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;machine: 1
313
\$Configuration['Database']['Name'] = '$db_db';
562
313
            &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;public-address: ec2-50-19-24-186.compute-1.amazonaws.com</pre>
314
\$Configuration['Database']['User'] = '$db_user';
563
314
            
315
\$Configuration['Database']['Password'] = '$db_pass';
564
315
            <p>Note how mysql is listed as started, while drupal's state is install_error. This is because the install hook has an error, and did not exit cleanly (exit code 1).</p>
316
EOF
565
316
            <h2>Debugging hooks</h2>
317
566
317
            <p>Let's debug the install hook, from a new window:</p>
318
juju-log "Make the application port available, now that we know we have a site to expose"
567
318
            <pre>juju debug-hooks drupal/0</pre>
319
568
319
            
320
open-port 80
569
320
            <p>This will connect you to the drupal machine, and present a shell. The way the debug-hooks functionality works is by starting a new terminal window instead of executing a hook when it is triggered. This way you get a chance of running the hook manually, fixing any errors and re-running it again. In order to trigger re-running the install hook, from another window:</p>
321
570
321
            <pre>juju resolved --retry drupal/0</pre>
322
</pre>
571
322
            
323
572
323
            <p>Switching to the debug-hooks window, you will notice a new window named &quot;install&quot; popped up. Note that &quot;install&quot; is the name of the hook that this debug-hooks session is replacing. We change directory into the hooks directory and rerun the hook manually:</p>
324
<p>You will notice that this script uses the backticked command <span class="pre">relation-get</span>. This is a Juju helper command that fetches the named values from the corresponding hook on the service we are connecting to.
573
324
            <pre>$ cd /var/lib/juju/units/drupal-0/charm/hooks/
325
Usually there will be some indication of what these values are, but you can always inspect the corresponding hoks to find out. In this case we know that when connected, the MySQL charm will create a database and generate random values for things like a username and password.</p>
574
325
            $ ./install
326
<p>These values will all be set at one time, so the next little bit of script just checks one value to see if it exists - if not the corresponding charm hasn't set the values yet.</p>
575
326
            # -- snip --
327
<p>When it has the values we can use these to modify the config file for Vanilla in the relevant place, and finally open the port to make the service active.</p>
576
327
            + cd /var/ww
328
<p>The final hook we need to write is for other services which may want to consume Vanilla, 'website-relation-joined'.</p>
577
328
            ./install: line 10: cd: /var/ww: No such file or directory
329
<pre class="prettyprint">#!/bin/sh
578
329
            </pre>
330
579
330
            
331
relation-set hostname=`unit-get private-address` port=80
580
331
            <p>Problem identified. Let's edit the script, changing ww into www. Rerunning it again should work successfully. This is why it is very good practice to write hook scripts in an idempotent manner such that rerunning them over and over always results in the same state. Do not forget to exit the install window by typing &quot;exit&quot;, this signals that the hook has finished executing successfully. If you have finished debugging, you may want to exit the debug-hooks session completely by typing &quot;exit&quot; into the very first window Window0</p>
332
</pre>
581
332
            
333
<p>Here we can see the other end of the information sharing - in this case <span class="pre">relation-set</span> exposes the given values to the connecting charm. In this case one of the commands is backticked, as <span class="pre">unit-get</span> is another helper command, in this case one which returns the requested value form the machine the charm is running on, specifically here it's IP address.
582
333
            <p>Note</p>
334
 So, any connecting charm will be able to ask for the values 'hostname' and 'port'. Remember, once you have finished writing your hooks make sure you 'chmod +x' them.</p>
583
334
            <p>While we have fixed the script, this was done on the remote machine only. You need to update the local copy of the charm with your changes, increment the revision number in the revision file and perform a charm upgrade to push the changes, like:</p>
335
<p>For our simplistic charm, that is all the hooks we need for the moment, so now we can test it out!</p>
584
335
            <pre>juju upgrade-charm --repository=examples/ drupal</pre>
336
</div>
585
336
            
337
<span class="number"> 5 </span>
586
337
            <p>Let's continue after having fixed the install error:</p>
338
          <div class="step" id="step05">
587
338
            <pre>juju add-relation mysql drupal</pre>
339
          <h2>Testing</h2>
588
339
            
340
          <p>Before we congratulate ourselves too much, we should check that the charm actually works. To help with this, we should open a new terminal window and run the following command:</p>
589
340
            <p>Watching the debug-log window, you can see debugging information to verify the hooks are working as they should. If you spot any error, you can launch debug-hooks in another window to start debugging the misbehaving hooks again. Note that since &quot;add-relation&quot; relates two charms together, you cannot really retrigger it by simply issuing &quot;resolved --retry&quot; like we did for the install hook. In order to retrigger the db-relation-changed hook, you need to remove the relation, and create it again like so:</p>
341
          <pre>juju debug-log</pre>
590
341
            <pre>juju remove-relation mysql drupal
342
          <p>This starts a process to tail the juju log file and show us just exactly what is happening. It won't do much to begin with, but you should see messages appearing when we start to deploy our charm.</p>
591
342
            juju add-relation mysql drupal</pre>
343
          <p>Following our own recipe, in another terminal we should now do the following (assuming you already have a bootstrapped environment):</p>
592
343
            
344
          <pre>juju deploy mysql
593
344
            <p>The service should now be ready for use. The remaining step is to expose it to public access. While the charm signaled it needs port 80 to be open, for public accessibility, the port is not open until the administrator explicitly uses the expose command:</p>
345
juju deploy --repository=/home/evilnick/localcharms/ local:precise/vanilla
594
345
            <pre>juju expose drupal</pre>
346
juju add-relation mysql vanilla
595
346
            
347
juju expose vanilla
596
347
            <p>Let's see a status with the ports exposed:</p>
348
</pre>
597
348
            <pre>
349
<p>We used the local deploy options to deploy our charm - substitute the path for your own environment. Everything should now be working away, and your log window will look something like this:</p>
598
349
            juju status
350
599
350
            
351
          <img src="./media/author-charm-writing-debug.png" width='600' alt="Step five - debug">  
600
351
            machines:
352
<p>If you wait for all the Juju operations to finish and run a <span class="pre">juju status</span> command, you will be able to retrieve the public address for the Vanilla forum we just deployed. Copy it into your browser and you should see the setup page (prepopulated with the database config) waiting for any changes. Congratulations!</p>
601
352
            &nbsp;0:
353
          <img src="./media/author-charm-writing-vanilla.png" width='600' alt="Step five - vanilla">           
602
353
            &nbsp;&nbsp;&nbsp;agent-state: running
354
603
354
            &nbsp;&nbsp;&nbsp;dns-name: ec2-50-16-107-102.compute-1.amazonaws.com
355
          
604
355
            &nbsp;&nbsp;&nbsp;instance-id: i-130c9168
356
          </div>
605
356
            &nbsp;&nbsp;&nbsp;instance-state: running
357
606
357
            &nbsp;1:
358
<span class="number"> 6 </span>
607
358
            &nbsp;&nbsp;&nbsp;agent-state: running
359
          <div class="step" id="step06">
608
359
            &nbsp;&nbsp;&nbsp;dns-name: ec2-50-19-24-186.compute-1.amazonaws.com
360
          <h2>Tidying up</h2>
609
360
            &nbsp;&nbsp;&nbsp;instance-id: i-17079a6c
361
          <p>With the charm working properly, you may consider everything a job well done. If your charm is really great and you want to share it, particularly on the charm store, then there are a couple of things you ought to add.</p>
610
361
            &nbsp;&nbsp;&nbsp;instance-state: running
362
          <ol>
611
362
            &nbsp;2:
363
612
363
            &nbsp;&nbsp;&nbsp;agent-state: running
364
          <li>Create a file called 'copyright' and place whatever license information you require in there. </li>
613
364
            &nbsp;&nbsp;&nbsp;dns-name: ec2-23-20-194-198.compute-1.amazonaws.com
365
          <li>Add a beautiful icon (<a href="./authors-charm-icon.html">there is a guide to making one here</a>) so others can recognise it in the charm store!</li>
614
365
            &nbsp;&nbsp;&nbsp;instance-id: i-d7079aac
366
          </ol>
615
366
            &nbsp;&nbsp;&nbsp;instance-state: running
367
          </div>  
616
367
            &nbsp;services:
368
                  
280
368
            &nbsp;mysql:
281
369
            &nbsp;&nbsp;charm: cs:precise/mysql-3
282
370
            &nbsp;&nbsp;relations:
283
371
            &nbsp;&nbsp;&nbsp;db:
284
372
            &nbsp;&nbsp;&nbsp;- drupal
285
373
            &nbsp;&nbsp;&nbsp;units:
286
374
            &nbsp;&nbsp;&nbsp;&nbsp;mysql/0:
287
375
            &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;agent-state: started
288
376
            &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;machine: 2
289
377
            &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;public-address: ec2-23-20-194-198.compute-1.amazonaws.com
290
378
            &nbsp;&nbsp;drupal:
291
379
            &nbsp;&nbsp;&nbsp;charm: cs:precise/drupal-3
292
380
            &nbsp;&nbsp;&nbsp;exposed: true
293
381
            &nbsp;&nbsp;&nbsp;relations:
294
382
            &nbsp;&nbsp;&nbsp;&nbsp;db:
295
383
            &nbsp;&nbsp;&nbsp;&nbsp;- mysql
296
384
            &nbsp;&nbsp;&nbsp;units:
297
385
            &nbsp;&nbsp;&nbsp;&nbsp;drupal/0:
298
386
            &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;agent-state: started
299
387
            &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;machine: 1
300
388
            &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;open-ports:
301
389
            &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;- 80/tcp
302
390
            &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;public-address: ec2-50-19-24-186.compute-1.amazonaws.com</pre>
303
391
            
304
392
            <p>Congratulations, your charm should now be working successfully! The db-relation-changed hook previously shown is not suitable for scaling drupal to more than one node, since it always drops the database and recreates a new one. A more complete hook would need to first check whether or not the DB tables exist and act accordingly. Here is how such a hook might be written:</p>
305
393
            <pre>#!/bin/bash 
306
394
            &nbsp;>set -eux # -x for verbose logging to juju debug-log
307
395
            &nbsp;<p>hooksdir=$PWD
308
396
            &nbsp;user=`relation-get user`
309
397
            &nbsp;password=`relation-get password`
310
398
            &nbsp;host=`relation-get host`
311
399
            &nbsp;database=`relation-get database`
312
400
            &nbsp;# All values are set together, so checking on a single value is enough
313
401
            &nbsp;# If $user is not set, DB is still setting itself up, we exit awaiting next run
314
402
            &nbsp;[ -z "$user" ] &amp;&amp; exit 0
315
403
            &nbsp;
316
404
            &nbsp;if $(mysql -u $user --password=$password -h $host -e 'use drupal; show tables;' | grep -q users); then
317
405
            &nbsp;juju-log "Drupal already set-up. Adding DB info to configuration"
318
406
            &nbsp;cd /var/www/juju/sites/default
319
407
            &nbsp;cp default.settings.php settings.php
320
408
            &nbsp;sed -e "s/USER/$user/" \
321
409
            &nbsp;-e "s/PASSWORD/$password/" \
322
410
            &nbsp;-e "s/HOST/$host/" \
323
411
            &nbsp;-e "s/DATABASE/$database/" \
324
412
            &nbsp;$hooksdir/drupal-settings.template &gt;&gt; settings.php
325
413
            &nbsp;else
326
414
            &nbsp;juju-log "Setting up Drupal for the first time"
327
415
            &nbsp;cd /var/www/juju &amp;&amp; drush site-install -y standard \
328
416
            &nbsp;&nbsp;--db-url=mysql://$user:$password@$host/$database \
329
417
            &nbsp;&nbsp;--site-name=juju --clean-url=0
330
418
            &nbsp;fi
331
419
            &nbsp;cd /var/www/juju &amp;&amp; chown www-data sites/default/settings.php
332
420
            &nbsp;open-port 80/tcp
333
421
            </pre>
334
422
            
335
423
            
336
424
            <p class="first admonition-title">Note</p>
337
425
            <p class="last">Any files that you store in the hooks directory are transported as is to the deployment machine. You can drop in configuration files or templates that you can use from your hook scripts. An example of this technique is the drupal-settings.template file that is used in the previous hook. The template is rendered using sed, however any other more advanced template engine can be used</p>
338
426
            
339
427
            <p><p>Here is the template file used:</p>
340
428
            <pre>$databases = array (
341
429
            &nbsp;'default' =&gt;
342
430
            &nbsp;array (
343
431
            &nbsp;&nbsp;&nbsp;&nbsp;'default' =&gt;
344
432
            &nbsp;&nbsp;&nbsp;&nbsp;array (
345
433
            &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'database' =&gt; 'DATABASE',
346
434
            &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'username' =&gt; 'USER',
347
435
            &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'password' =&gt; 'PASSWORD',
348
436
            &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'host' =&gt; 'HOST',
349
437
            &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'port' =&gt; '',
350
438
            &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'driver' =&gt; 'mysql',
351
439
            &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;'prefix' =&gt; '',
352
440
            &nbsp;&nbsp;&nbsp;&nbsp;),
353
441
            &nbsp;&nbsp;),
354
442
            &nbsp;);
355
443
            </pre>
617
444
          </article>
369
          </article>
618
445
        </div>
370
        </div>
619
446
      </div>
371
      </div>
620
@@ -498,6 +423,7 @@
621
498
      <p><a href="https://bugs.launchpad.net/juju-website/+filebug">Report a bug on this site</a></p>
423
      <p><a href="https://bugs.launchpad.net/juju-website/+filebug">Report a bug on this site</a></p>
622
499
    </div>
424
    </div>
623
500
  </div>
425
  </div>
624
426
  <script src="https://google-code-prettify.googlecode.com/svn/loader/run_prettify.js?skin=sunburst"></script>
625
501
</footer>
427
</footer>
626
502
428
627
503
    <script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js"></script>
429
    <script type="text/javascript" src="//ajax.googleapis.com/ajax/libs/jquery/1.6.2/jquery.min.js"></script>
628
504
430
629
=== modified file 'htmldocs/charms-deploying.html'
630
--- htmldocs/charms-deploying.html	2013-07-15 13:01:43 +0000
631
+++ htmldocs/charms-deploying.html	2013-07-25 01:29:31 +0000
632
@@ -116,7 +116,7 @@
633
116
             <p>which follows the format:</p>
116
             <p>which follows the format:</p>
634
117
             <pre><code>&LT;repository&GT;:&LT;series&GT;&LT;service&GT;</code></pre>
117
             <pre><code>&LT;repository&GT;:&LT;series&GT;&LT;service&GT;</code></pre>
635
118
             
118
             
637
119
             <h1>Deploying from a local repository</h1>
119
             <h1 id="local">Deploying from a local repository</h1>
638
120
             <p>There are many cases when you may wish to deploy charms from a local filesytem source rather than the charm store:</p>
120
             <p>There are many cases when you may wish to deploy charms from a local filesytem source rather than the charm store:</p>
639
121
             <ul>
121
             <ul>
640
122
              <li>When testing charms you have written.</li>
122
              <li>When testing charms you have written.</li>
641
@@ -126,7 +126,7 @@
642
126
             <p>... and probably a lot more times which you can imagine yourselves.</p>
126
             <p>... and probably a lot more times which you can imagine yourselves.</p>
643
127
             <p>Juju can be pointed at a local directory to source charms from using the <span class="pre">--repository=&LT;path/to/files&GT;</span> switch like this:</p>
127
             <p>Juju can be pointed at a local directory to source charms from using the <span class="pre">--repository=&LT;path/to/files&GT;</span> switch like this:</p>
644
128
             
128
             
646
129
             <pre><code>juju deploy --repository=/usr/share/charms/ vsftpd</code></pre>
129
             <pre><code>juju deploy --repository=/usr/share/charms/ local:precise/vsftpd</code></pre>
647
130
             <p>You can also make use of standard filesystem shortcuts, so the following examples are also valid:</p>
130
             <p>You can also make use of standard filesystem shortcuts, so the following examples are also valid:</p>
648
131
             <pre><code>juju deploy --repository=. haproxy</code></pre>
131
             <pre><code>juju deploy --repository=. haproxy</code></pre>
649
132
             <pre><code>juju deploy --repository=~/charms/ wordpress</code></pre>  
132
             <pre><code>juju deploy --repository=~/charms/ wordpress</code></pre>  
650
133
133
651
=== added file 'htmldocs/media/author-charm-writing-debug.png'
652
134
Binary files htmldocs/media/author-charm-writing-debug.png	1970-01-01 00:00:00 +0000 and htmldocs/media/author-charm-writing-debug.png	2013-07-25 01:29:31 +0000 differ
134
Binary files htmldocs/media/author-charm-writing-debug.png	1970-01-01 00:00:00 +0000 and htmldocs/media/author-charm-writing-debug.png	2013-07-25 01:29:31 +0000 differ
653
=== added file 'htmldocs/media/author-charm-writing-log.png'
654
135
Binary files htmldocs/media/author-charm-writing-log.png	1970-01-01 00:00:00 +0000 and htmldocs/media/author-charm-writing-log.png	2013-07-25 01:29:31 +0000 differ
135
Binary files htmldocs/media/author-charm-writing-log.png	1970-01-01 00:00:00 +0000 and htmldocs/media/author-charm-writing-log.png	2013-07-25 01:29:31 +0000 differ
655
=== added file 'htmldocs/media/author-charm-writing-vanilla.png'
656
136
Binary files htmldocs/media/author-charm-writing-vanilla.png	1970-01-01 00:00:00 +0000 and htmldocs/media/author-charm-writing-vanilla.png	2013-07-25 01:29:31 +0000 differ
136
Binary files htmldocs/media/author-charm-writing-vanilla.png	1970-01-01 00:00:00 +0000 and htmldocs/media/author-charm-writing-vanilla.png	2013-07-25 01:29:31 +0000 differ
657
=== modified file 'skel/footer.tpl'
658
--- skel/footer.tpl	2013-07-15 13:01:12 +0000
659
+++ skel/footer.tpl	2013-07-25 01:29:31 +0000
660
@@ -50,4 +50,5 @@
661
50
      <p><a href="https://bugs.launchpad.net/juju-website/+filebug">Report a bug on this site</a></p>
50
      <p><a href="https://bugs.launchpad.net/juju-website/+filebug">Report a bug on this site</a></p>
662
51
    </div>
51
    </div>
663
52
  </div>
52
  </div>
664
53
  <script src="https://google-code-prettify.googlecode.com/svn/loader/run_prettify.js?skin=sunburst"></script>
665
53
</footer>
54
</footer>
Status:	Merged
Merged at revision:	36
Proposed branch:	lp:~evilnick/juju-core/docs-new-walkthrough
Merge into:	lp:juju-core/docs
Diff against target:	665 lines (+267/-340) 3 files modified htmldocs/authors-charm-writing.html (+264/-338) htmldocs/charms-deploying.html (+2/-2) skel/footer.tpl (+1/-0)
To merge this branch:	bzr merge lp:~evilnick/juju-core/docs-new-walkthrough
Related bugs:	Link a bug report
Reviewer	Review Type	Date Requested	Status
Marco Ceppi		2013-07-25	Pending
Review via email: mp+176833@code.launchpad.net