~jorge/juju-core/review-configs-for-bundles

          <article>

<h1>Your First charm starts here!</h1>

<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>

<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>

 

<span class="number"> 1 </span>

          <h2>Prepare yourself</h2>

          <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>

          <p>Go to your home directory (or wherever is appropriate and make the appropriate file structure:</p>

          

          </div>

 

<span class="number" > 2 </span>

          <div class="step" id="step02">

          <h2>Create the README file</h2>

          <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>

          <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>

          <p>Here is a quick example README file for our Vanilla charm:</p>

          <p>Obviously, you can include any useful info you wish.</p>

          </div>

          

          <h2>Make some metadata.yaml</h2>

          <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>

          <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 explanatory:</p>

          

 

          </div>         

          <h2>Writing hooks</h2>

          <p>As you will know from your thorough reading of the <a href="./authors-charm-components.html">charm components</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>

          <p>For our charm, the hooks we will need to create are:</p>

<p>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>

<p>For our simplistic charm, that is all the hooks we need for the moment, so now we can test it out!</p>

</div>

          <h2>Testing</h2>

          <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>

          <pre>juju debug-log</pre>

          

          </div>

 

          <h2>Tidying up</h2>

          <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>

          <ol>