Juju includes a collection of what we call
Charms that let you deploy whatever
services you want in Juju. A collection of charms that are designed to work
together is called a
Bundle. Since charms and bundles are open and worked on
by the community, they represent a distilled set of best practices for deploying
these services. Both charms and bundles are included in what we collectively
call The Charm Store.
- The main project page is here: https://launchpad.net/charms
- There are useful tools for downloading, modifying, and contributing here: https://launchpad.net/charm-tools
- Here is the official tutorial for charm authors: authors-charm-writing
- Here is the official tutorial for bundle authors: charms-bundles
There are currently 2 methods to submit a charm and have it listed in the charm store. Both methods have their perks - but it is suggested to start with your personal namespace before asking for a charmer featured charm.
Note: if you are a member of the Charm Partner Program, you will want to ensure that your Charm gets into the Recommended Charms section of the Charm Store, so please follow the instructions in the Recommended Charms section below.
This process is designed to allow prospective developers to have their charms reviewed and updated in the Charm Store in a timely manner that ensures peer reviews and quality.
Everyone with a launchpad account has access to have their charms listed in the charm store, without review, approximately 20 minutes after the initial push to their launchpad branch. Authors are free to request ~charmer/peer review from their personal name space branch.
You can submit your charm to the 12.04 and 14.04 releases of Ubuntu. You are not required to submit to both releases, but we recommend supporting both whenever possible so that users get the most flexibility:
- Install juju and charm-tools.
- Create a repository, something like
mkdir -p ~/charms/precise; 'precise' is the release code name for the release of Ubuntu you wish to target your charm at. You can also use
trustyif you're submitting to that series.
- If you haven't created your charm yet, you can use
charm create ubuntu-package-namewhich will fill in some basic metadata info for you. You can check to see if it already exists at https://jujucharms.com/. Also make sure to check the list of open bugs to see if anybody is already working on a charm for the service you want to work on. Bugs which have had no activity by the assignee for more than 30 days are fair game and should be unassigned.
- Once your charm is working and tested with any compatible charms, make sure
charm proof path/to/your/charm
bzr initin your charm's root directory
bzr addto add all files.
bzr ci -m'Initial charm'
- To submit your charm for 12.04:
bzr push lp:~<your-lp-username>/charms/precise/<your-charm>/trunk
or to submit your charm for 14.04:
bzr push lp:~<your-lp-username>/charms/trusty/<your-charm>/trunk
Your charm should then be looked at in a timely manner.
There are some key differences with regard to deployment charms in your personal namespace.
- Submission Process
- Charm Store Display
- Workflow to accept contributions
When you feel your charm is ready for submission to your personal name space, you must initialise the repository and push your development branch to Launchpad.
For the purpose of this documentation, we will call our charm
bzr push lp:~your-launchpad-username/charms/series/nagios/trunk
The /trunk branch identifier is the only branch that will be recognised by the charm store ingestion process. This frees the developer to push multiple branches and gate features/fixes into their personal branch without listing multiple copies of the charm in the store.
To break down the launchpad link structure, the segments will be listed in bold with a description following.
- lp:~username : This is your launchpad username
- /charms/ : Charms is the project descriptor
- /precise/ : All charms are targeted against a series
- /nagios/ : This is the charm name and should match whats listed in metadata.yaml
- /trunk : The branch target. Remember only /trunk will be ingested into the charm store.
Once your charm has been ingested it will be deployable via your personal name space URL.
juju deploy cs:~your-launchpad-username/series/nagios
Name Spaced charms will be displayed under the other category in the GUI. They will be displayed with non-descript icons for the service. Only recommended charms display the shipped icon for the service.
To accept contributions, and/or merge patches into your personal namespace - as the owner of the charm, you are responsible for reviewing and accepting/rejecting contributions.
bzr push lp:~<your-lp-username>/charms/series/nagios/feature_branch
and a subsequent Merge Proposal should be issued against your branch following the Launchpad Developer Merge Proposal Documentation
To have your charm listed as a charmer team recommended charm, you have to undergo a rigorous review process where the team evaluate the charm, evaluate tests for your charm, and deploy & run tests against the provided service with different configuration patterns.
After following the Submission Process outlined above:
- File a bug against charms at https://launchpad.net/charms/+filebug This is used to track the progress of your charm.
- Now you just need to attach your branch to the bug report, go to your code page, find your branch and click on it. Then click on "Link a bug report", and put in the number of the bug you filed. If you are submitting to multiple releases please make one bug per release.
- Subscribe the
charmersteam by clicking "Subscribe someone else" on the right side of the launchpad page. This is important as it gets your charm in the review queue!
- Grab the charm you want to fix, we'll use Nagios as an example:
bzr branch lp:charms/precise/nagios
- Modify it to meet your needs.
- Commit your fixes
bzr commit -m 'Your changelog entry goes here'
bzr push lp:~your-launchpad-username/charms/precise/nagios/fixed-charms-name
- Submit a merge proposal
by going to your branch's code page:
https://code.launchpad.net/~your-launchpad-username/charms/precise/nagios/fixed-charms-nameand clicking "Propose for merging"
- In the merge proposal form select the charm's lp name:
lp:charms/nagiosfor the target branch, if not already selected.
- For the reviewer field put the
charmersteam, this will get your code into the review queue!
Refer to the Bundles page for instructions on how to create bundles of charms and submit them to the store.
Inspired by Bazaar's Patch Pilot programme there will be patch pilots in #juju who can help you get your patch accepted. Check the topic to see who's on duty. Still need help? Contact us on the Juju mailing list ; if you're from an upstream project who wants more detailed help/tutoring, then contact Jorge Castro and we'd be more than happy to get a charm expert to help you out or help you run a Charm School.
- Please respect that these people might have a few other charms in their queue already.
- The package you have a question about might not necessarily be part of the patch pilot's area of expertise. They will still try to help you get your fix in and probably get you in touch with the 'right' people.