there seem to be old template files etc which no longer need to be in the repo.

We should support and promote this syntax:

juju bootstrap
juju deploy something
juju do-something-else

over the indentation syntax for code samples.

1. It is Github standard
2. It means not having things break because you can't tell how many spaces you added.
3. It is already supported by python-markdown - http://pythonhosted.org/Markdown/extensions/fenced_code_blocks.html

There has been a request for more information regarding Windows/Centos deployments. Specifically one issue raised was about driver failures during deploy. We should try and capture these problems and store solutions in the troubleshooting section.

See juju-core/doc/azure-provider.txt, or ask me for more info.

We have a ton of logging information under troubleshooting. While that's great - logging is a topic all unto itself and should reside on its own topic page in the user docs with proper topic headings.

The developer logging can be summed up by explaining the different logging levels and juju log, which I believe is already in the author docs.

Currently all pages are titled Juju Documentation. Adding a dash followed by the headline of the page would help to get aware of current location in the docs.

The "Charm Store review Criteria" is too long to fit in the nav

A customer asked recently for a link to the Juju API documentation. I searched Google for "juju api" and got no relevant hits on the first 2 pages. When I asked in #juju, I did get an answer:

http://godoc.org/github.com/juju/juju/api

So that's autogenerated documentation, which is more or less what we were looking for, but quite hard to find.

This bug is requesting that we host/mirror that documentation on one of the official Juju sites (juju.ubuntu.com or jujucharms.com), wherever is more appropriate, and setup appropriate Google indexing of such documentation.

A note on logging for HA. This should be part of the HA docs, when we have them.

Logging with HA

When running JuJu with HA (ensure-availability) logging is done to all state servers. "juju debug-log" connects to a random state server, but you'll still see logs from all the state servers and all units. This means that if your master (term?) state server dies, you'll still have logs on the other state servers and still see new logging.Essentially this means that logging works the same with HA as it does without HA. You can use "juju debug-log", or ssh into a state server and view the log file directly, to see all the logs.

Logging to a state server starts once a new state server comes online, i.e. after running ensure-availability. So if your master state server dies you will lose the logs from before new state servers were started.This will be fixed at some point, so new state servers will have all existing logs synced to them when they come online. This is not currently the case.

You need to proof a directory, not a file, and the directory needs to follow the right structure.

It should be sshuttle -r vagrant@localhost:2222 10.0.3.0/24 instead of what it currently is

I was recently reviewing the Juju documentation for adding tests to charms and while the examples were reasonable (some walkthrough would be nice), the documentation regarding getting the tests set up (as well as the get-unit-info) is outright confusing.

Here is the content:

get-unit-info The example tests script uses a tool that is not widely available yet, 
get-unit-info. In the future enhancements should be made to juju core to allow 
such things to be made into plugins. Until then, it can be included in each test 
dir that uses it, or we can build a package of tools that are common to tests.

1. After digging around the Juju documentation, I managed to find juju charm add tests in the Charm Tools section, however when I used it, it created 00-autogen and 00-setup, which are python scripts. Unlike the charm create tool, there is no way of defining that I wanted bash instead of python, which just left me confused.
2. There is no documentation anywhere on get-unit-info, from what I can tell, nor is it included in the test directory (at least when using charm add tests).

I think the following needs to happen in relation to this bug:

1. The testing doc needs to have an updated get-unit-info section or offer a completely different alternative that works for both bash and python.
2. The testing doc needs to offer clarity on how to easily generate tests in the first place, linking to the tools-charm-tools page.
3. I'd like to think a secondary bug should be opened somewhere (if one doesn't exist already), that offers a -t {python,bash} option for charm add tests (probably in the juju Github project).

Until then, I'm left slightly puzzled where to go with these tests. The examples only lead me so far and according to @mbruzek, I need tests to land to land in trusty charm store (so people could do juju deploy x rather than juju deploy lp:[...]).

16.1, 16.2 etc

Hello,

The only publicly available reference I can locate for doing off-line Juju deployments is https://juju.ubuntu.com/docs/howto-offline-charms.html.

However, there are a few other things we also should be covering on this document:

1. How to synchronize the juju tools locally.
2. Setting up a package mirroring using apt-proxy for packages update/install
3. Configure squid or http/https proxy
4. How to deal with charms that requires internet access for fetching arbitrary resources.
5. Step by step example of an off-line deployment.

The currently needed sudo to bootstrap a local environment is not needed anymore. User will be asked during bootstrapping. This has to be changed in

https://juju.ubuntu.com/docs/config-LXC.html
https://juju.ubuntu.com/docs/troubleshooting-local.html

Adam Israel has removed the dependency on sshuttle, and we should probably remove this from the workflow docs and replace it with his new and improved workflow - as sshuttle dumps core on yosemite. Not an awesome experience for new users.

There are two problems with the first section in authors-implicit-relations:

problem 1.

This paragraph is confusing about what you can accomplish with implicit relations:

Implicit relations allow for interested services to gather lifecycle-oriented events and data about other services without expecting or requiring any modifications on the part of the author of the other service's charm.

This makes it sound like an arbitrary service A (that is not related to anything) can use the juju-info implicit relation to have juju call juju-info* hooks on A when two other services B & C are deployed, or exchange relation info between each other.

After asking around and with some trial and error, this does not appear to be the case.

Implicit relations appear to be only useful for subordinate charms, which is not mentioned in these docs.

problem 2.

The docs do not show any example usage of the relations.

The only example code is the notional interface declaration we are warned not to use.

Ideally there would be a sample metadata.yaml showing how you inform juju that you want to use the juju-info relation, and a sample charm hook showing how you get information from it and what it might be useful for.

The generation of links for the previous, the top section, and the next document at the head and the food of the pages help at sequential reading of the docs.

Long-time linuxer, first-time jujuer ...

Setting up an Azure environment as my first exposure to juju, I was stymied by the angle brackets on the dummy management-subscription-id. Pasting the proper string in over the dummy string but leaving the brackets leads to a failed environment with unhelpful messages. I eventually found the remark about the angle brackets denoting text to replace but the convention is not universal and the comment does not make it clear that you have to replace the brackets along with the text.

https://juju.ubuntu.com/docs/howto-node.html is pointing at using juju deploy --config myapp.yaml node-app myapp.
However myapp.yaml is wrong, there is no repo options, it seems to be app_url instead.
Also, the config example should reflect the name of the charm.

More IRC context:
didrocks | I have a small question, on jcastro's advice, I'm following https://juju.ubuntu.com/docs/howto-node.html
didrocks | I was wondering about the node-app charm to set the right repo
didrocks | it's pointing at juju deploy --config myapp.yaml node-app myapp
didrocks | with the yaml being:
didrocks | sample-node:
didrocks | repo: https://github.com/yourapplication
didrocks | however, in the charm itself (http://manage.jujucharms.com/charms/precise/node-app), I see that the config is using app_url
didrocks | I'm probably missing one transformation step :)
lazyPower | didrocks: you discovered a bug in the docs, good catch.
lazyPower | didrocks: would you mind filing a bug? https://github.com/juju/docs
didrocks | lazyPower: ah nice, can do, for sure, so the name should be mapping the charm config?
jose | didrocks, lazyPower: I can fix it right now
didrocks | jose: still want the bug opened?
jose | ask lazyPower!
lazyPower | didrocks: when you say name should be mapping the charm config, what do you mean?
didrocks | lazyPower: options in the yaml config like "repo" should be the one in the charm config options
jcastro | the config is missing on the charm page
jcastro | I think the docs are referring to a config option that either doesn't exist, or used to exist and bitrotted
lazyPower | well, looking at the docs, this is really confusing, a) there is no repo config options, its app_url
didrocks | yeah, seems to be app_url
lazyPower | and the name at the top of that config example should reflect the name of the charm
lazyPower | eg, if you deploy node-app charm as "hoobadooba", it should read: hoobadooba: app_url: http://myawesomegithub.git
didrocks | oh, so not "sample-node" but "node-app"?
lazyPower | right
didrocks | ah ok :)

https://juju.ubuntu.com/docs/authors-charm-interfaces.html no longer contains the list/example interface

Similar to #85. We now have support for automatic spread of units across availability zones in ec2, and support is not far away for openstack. We should call this out somewhere prominent.

As it stands now for the GFM / Juju markdown converter, it converts every single markdown file residing in src/en to HTML, even if only a single file has changed.

I propose an improvement to the converter that creates an sha1sum of each markdown file (src/en/*.md). On compile-time, it compares the stored sha1sum (could be in PROJECTROOT/sha1sums/*.md) with the sha1sum of the src/en/*.md file. If there is a difference, it adds it to an array of files that need to be converted. At the end of the checking, it will convert those files.

Theoretically that will reduce the overall conversion time.

Another idea, raised by @marcoceppi, was to have a file watcher that'd get called whenever a file is changed and automatically convert it.

In order to form a more perfect HTML doc and avoid crazy rendering issues we should link up with Travis CI and perform a lint of all the files.

I also suggest adding a Makefile which will properly lint so the user doesn't have to submit a pull request just to have the linting run.

Right now screenshots live in htmldocs/media. Since we plan to gitignore this directory I recommend we put them in src/en/media so that contributors don't have to copy them to the generated directory, which we want them to not use anyway.

Should just need to update navigation.tpl in src as we're statically generating the pages now

the deploy page doesn't include any example of passing --config options

it is the manual provider now

The current page at:
https://juju.ubuntu.com/docs/authors-charm-store.html
buries the need to open a bug too deep in the page. Our partners are consistently missing that step as it in non-obvious that they need to file a bug to get a review.

Proposal:

Change this paragraph
"Charm Store Submission

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

to this:

Charm Store Submission

There are currently two (2) methods to submit a Charm and to have it listed in the Charm store. They are outlined below.

<indent & bold>
Important 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 ensure to follow the instructions in the "Recommended Charms" section below.
</indent & blod>

Both Charm submission methods have their perks - but it is suggested to start with your personal namespace before asking for a charmer featured charm.

I think documenting every single command in the docs is going to be impossible, unless we start auto-generating the help from juju-core itself. How do we feel about removing this page?

Write up instructions for block/unblock as per below

Anastasia Macmood
Jan 9 (7 days ago)

to juju-dev
I have recently worked on blocking juju commands. If you are creating
new commands, you may find this helpful :-)

PROBLEM
Customers and stakeholders want to be able to prevent accidental damage
to their Juju deployments.

SOLUTION
To prevent running some commands, we have introduced a concept of
command block. Once the block is switched on, it has to be manually
switched off to run commands successfully.

There are currently three types of blocks developed.
DESTROY_BLOCK blocks destroy-environment command.
REMOVE_BLOCK blocks destroy-environment as well as all object removal -
machines, services, units, relations.
CHANGE_BLOCK blocks all commands from DESTROY and REMOVE blocks as well
as all environment modifications.
For more information and the list of all commands that are blocked, run
juju help block or juju help unblock.

to me
Hi Nick

The most up-to-date list would be produced by running either juju help block or juju help unblock.

For 1.22, this list will look like this :)

DESTROY_BLOCK:
destroy-environment

REMOVE_BLOCK:
destroy-environment
remove-machine
remove-relation
remove-service
remove-unit

CHANGE_BLOCK
add-machine
add-relation
add-unit
authorised-keys add
authorised-keys delete
authorised-keys import
deploy
destroy-environment
expose
remove-machine
remove-relation
remove-service
remove-unit
resolved
retry-provisioning
run
set
set-constraints
set-env
unexpose
unset
unset-env
upgrade-charm
upgrade-juju
user add
user change-password
user disable
user enable

We should ensure there are no broken links in our docs, we should fix lint.py to check URLs. This avoids us linking to missing vagrant boxes, as a real world example.

There's now support (on trunk) for juju bootstrap/add-machine to take an optional environment-specific placement directive. MAAS is the only provider that currently supports such directives; we use this to bootstrap/add machines based on specific nodes in MAAS.

e.g.
juju bootstrap
juju add-machine

I am imagining AGPL is most appropriate, as docs are most often hosted, but open for discussion.

E.g. the menu How hooks are run currently leads to a page with the headline Hook execution environment. This may lead to some confusion when navigating through the docs.

See #13

juju run executes as different users in different contexts.
You can validate this assertion by running whoami in the context.

• --service
• --unit
• --all
• --machine

For example, as mentioned in #206
apt-proxy and many other config options are not currently documented. It would help to know what they all are to begin with

Juju retry-provisioning

You can use the retry-provisioning command in cases where deploying
services, adding units, or adding machines fails. The command allows you
to specify machines which should be retried to resolve errors reported
in status.

For example, after you deployed 100 units and machines, status reports
that machines 3, 27 and 57 could not be provisioned because of a rate
limit exceeded error. You can ask juju to retry:

juju retry-provisioning 3 27 5

The Charm Store Policy at https://juju.ubuntu.com/docs/authors-charm-policy.html says:

"Should make use of AppArmor to increase security."

It would be nice to provide documentation about how charms should handle apparmor. I believe this is usually handled at the package level, but not all packages will have it, and some charms may not install using packages.

Background: I noticed that the !!! Notes: syntax from the custom Juju markdown was not working on several documents prior to my #146 pull. Upon pushing #146 with changes to switch !!! Note: to **Note:**, the Note blocks worked.

Some of the affected files were reverted in #152 by @mbruzek (him and I were under the belief that the note block syntax did in fact work). I have since reviewed those documents on juju.ubuntu.com, an example of such revert not working is the Charms Working with Units file.

I was unaware of the syntax not working until I reviewed the live document of the Charm Review Process, which leverages the !!! Note: syntax. I would appreciate the converter being fixed to properly change the note syntax to the p[class="note"], or preferably deprecated entirely.

Until this issue is fixed, does anyone object to me swapping out !!! Note: to **Note:** in the affected docs? I'd be happy to revert those changes later on once the issue is resolved.

With 1.18 the command destroy-environment always needs the environment name as argument. Has to be changed in

https://juju.ubuntu.com/docs/charms-destroy.html

Juju unset-env

The unset-env command allows you to reset one or more the environment
configuration attributes to its default value in a running Juju
instance. Attributes without defaults are removed, and attempting to
remove a required attribute with no default will result in an error.
Multiple attributes may be removed at once; keys are space-separated.

This is probably a longer term goal, but for better SEO, we would like to set the page title for each HTML page instead of the default "Juju Documentation"

A possible way to implement this would be to use the Metadata extension for markdown. This would require some template processing but would enable us to set page titles independently of the HTML name of the page, which would be useful for different languages, for example.

Juju can run multiple local environments. To create a different local environment in Juju, define a new section in the .juju/environments.yaml file.

# mbruzek's local environment on this system.
local-mbruzek:
        type: local
        storage-port: 8041
        state-port: 37018
        api-port: 17071

The port numbers must be different than the default local port numbers which are 8040 for storage-port, 37017 for state-port, and 17071 for api-port.