The charm author can use the optional
config.yaml file to define a charm's
configuration. This file also becomes available to the end user if they choose
to download the charm in order to inspect it.
If this file is used, it must contain a dictionary of
options, in which every
setting is named by the key and defined by the value.
The following fields are available for an option:
type: can be
description: contains an explanation of what the user might achieve by altering the setting along with valid values.
default: contains a default value for the option. This value must be of the appropriate type and be coherent for the given charm.
The only required field is
type. Omitting it will cause an error to be
generated by the charm proof tool indicating
the option is not compliant with Charm Store policy.
Some options may need to be set, but depending on the nature of the charm it
may not be feasible to provide a default value. The author should list any such
options in the
description field. See
Application configuration for information on
configuring an application at deployment time.
A null default value is accepted for any option type (providing a non-null value is not mandatory). The following formats are valid:
The charm configuration is deliberately somewhat restrictive, in the hope of
encouraging charmers to expose only features that are clear and comprehensible.
The user doesn't want to configure the software - they want to configure the
service, which exists at a higher level of abstraction. A charm with a single
tuning option is, from this perspective, infinitely superior to
one that exposes 6 arcane options that correspond directly to flags or config
settings for the software.
In short, the config is part of the user interface for the charm - it needs to be concise and as easy to understand and use as possible. If you're considering using base64 encoding to slip structured data through the deliberately restrictive configuration language, you're probably "Doing It Wrong".
Your charm should operate correctly with no explicit configuration settings. The
first time someone uses your charm, they're likely to run
yourcharm and see what happens; if it doesn't work out of the box ont the first
go, many potential users won't give it a second try.
The MediaWiki has some simple but useful configuration options:
options: name: default: Please set name of wiki description: The name, or Title of the Wiki type: string skin: default: vector description: skin for the Wiki type: string logo: default: description: URL to fetch logo from type: string admins: default: description: Admin users to create, user:pass type: string debug: default: false type: boolean description: turn on debugging features of mediawiki