charms/README.md

   1 # Juju Charm usage and development
   2
   3 This document is intended to provide a brief overview of the components included
   4 in this repository as well as recommendations for how to develop, build, and
   5 publish charms.
   6
   7 Please read the [develper geting started guide](https://jujucharms.com/docs/2.0/developer-getting-started) before proceeding.
   8
   9 ## Directory structure
  10
  11 ```
  12 .
  13 ├── builds
  14 │   └── vpe-router
  15 ├── interfaces
  16 ├── layers
  17 │   └── vpe-router
  18 └── module-blueprints
  19 ```
  20
  21 The source code of a charm is referred to as a "layer". This layer is compiled
  22 into a charm and placed in the `builds/` directory. Interfaces, currently
  23 unused in this context, extend relationships between applications.
  24
  25 ## Development workflow
  26 ### Prepare your build environment
  27 ```
  28 # Source the environment variables JUJU_REPOSITORY, INTERFACE_PATH, and
  29 # LAYER_PATH, which are needed to build a charm. You could also place these
  30 # in your $HOME/.bashrc
  31 $ source juju-env.sh
  32 ```
  33 #### Install the `charm` command, either via apt:
  34
  35 ```
  36 $ sudo apt install charm
  37 ```
  38
  39 or with [snap](http://snapcraft.io/)
  40
  41 ```
  42 $ snap install charm --edge
  43 ```
  44
  45 To build a charm, simply run `charm build` inside of a layer.
  46 ```
  47 $ cd $LAYER_PATH/vpe-router
  48 $ charm build
  49 $ charm deploy $JUJU_REPOSITORY/builds/vpe-router
  50 ```
  51
  52 ## Publishing to jujucharms.com
  53
  54 Publishing to the Juju Charm store requires a launchpad login. With that, login
  55 to [jujucharms.com](http://www.jujucharms.com/).
  56
  57 Next, you'll use the charm command to publish your compiled charm. This will
  58 put the charm into the store where it can be used by anyone with access.
  59
  60 For example, if I wanted to publish the latest version of the vpe-router charm:
  61
  62 # Step 1: Upload the charm to the "unpublished" channel
  63 ```
  64 $ cd $JUJU_REPOSITORY/builds
  65 $ charm push vpe-router/ cs:~aisrael/vpe-router
  66 url: cs:~aisrael/vpe-router-0
  67 channel: unpublished
  68 ```
  69
  70 # There are four channels to release a charm: edge, beta, candidate, and stable
  71 ```
  72 $ charm release cs:~aisrael/vpe-router-0 --channel=edge
  73 url: cs:~aisrael/vpe-router-0
  74 channel: edge
  75 ```
  76 The charm can then be deployed directly from the charm store:
  77 ```
  78 $ juju deploy cs:~aisrael/vpe-router --channel=edge
  79 ```