/ 
App-CharmKit-1.0.8
River stage zero No dependents
/ App::CharmKit::Manual::GettingStarted

Getting Started

Creating a project

To start a project:

$ charmkit init [--with-hooks] <charm-name>

If used --with-hooks then hooks/ will be populated with all the default hooks. A few questions will be prompted and then the project is generated with charmkit.json, config.yaml, metadata.yaml, LICENSE, README.md, and Makefile.

Directory Layout

Once a project is created the structure of your project should look similar to:

charm-project/
  hooks/
    install
    config-changed
    start
    stop
  tests/
    00-basic.test
  config.yaml
  metadata.yaml
  LICENSE
  README.md
  charmkit.json
  Makefile

Creating hooks

By default CharmKit allows the creation of a set of default unit hooks. Those hooks are install, config-changed, start, upgrade-charm, stop.

$ charmkit generate upgrade-charm

Or you can generate all known default unit hooks:

$ charmkit generate -a

A special relation hook can be created with the -r option:

$ charmkit generate -r database-relation-joined

Writing charm hooks

Hooks are written using perl with automatically imported helpers for convenience. When developing hooks they should reside in hooks.

A typical hook starts with

#!/usr/bin/env perl

use charm;

log 'Starting install hook for database';

apt_install(['mysql-server', 'nginx', 'php5-fpm'])

my $dbhost = relation_get 'dbhost';
my $dbuser = relation_get 'dbuser';

service_control('nginx', 'restart');

Writing charm tests

Tests are written in the same way and should live in tests/*.test.

A typical test starts with

#!/usr/bin/env perl

use charm -tester;

# See if an nginx config file exists
ok (-e '/etc/nginx/sites-enabled/mysite.com', 'found nginx site config');

my $ret = service_status('nginx');
ok ($ret->{error} eq 0, 'nginx is running);

# finish tests
done_testing;

Tests are built in a way that the test runner from the charm reviewers will be able to run and validate your charm. The tests can be executed calling them directly (how the test runner does it) or running with:

$ charmkit test

or

$ prove -lv tests/*.test

Getting external charms

CharmKit currently supports git endpoints and GitHub syntax username/repo

$ charmkit clone battlemidget/test-charm -o ~/charms/trusty/test-charm

Deploying a charm

$ charmkit deploy test-charm -c ~/charms

The syntax above will allow Juju to find the local charm and which series it belongs too. A requirement of Juju is to have a proper directory structure in the format of charms/<series/<charmname>, where series could be any Distribution release your charm supports, (eg. trusty, precise).