Confluence Config Documentator (confdoc & confwatch)
A command line utility to document textual configurations files in Atlassian Confluence.
The name is a mouth full, but the concept behind confdoc is simple - to create and update Confluence pages with the content of a configuration text file (or any text file for that matter).
Installation
npm install -g confluence-config-documentator
Now you can type confdoc and confwatch on the command line.
GIT Cloning
If you are cloning / forking from GIT, run npm install to install dependencies.
git clone https://github.com/garyns/confluence-config-documentator
cd confluence-config-documentator
npm install
Confdoc Usage
confdoc is an commline tool to upload a file to Confluence.
confdoc --server <confluence_server_url> --username <username> --password <password> [--config <file>] [--spaceKey <key>] [--parentId <id>] [--pageId <id>] [--title <title>] [--query <string>] [--labels <labels>] [--macro <macro>] [--quiet] [--noupgrade] <input_file>
The following options are supported:
-e, --quiet Suspress non-error output
-v, --verbose Verbose output and full error messages
-n, --noupgrade Suspress new version check
-c, --config <ARG1> Configuration File (defaults to ~/.confdoc)
-s, --server <ARG1> Confluence Server URL
-u, --username <ARG1> Confluence Username
-p, --password <ARG1> Confluence Password
-f, --force Force page update even if no change in content
-k, --spaceKey <ARG1> Confluence Space Key
-o, --parentId <ARG1> Confluence Parent Page Id (when creating new page. Space root used if not specified)
-i, --pageId <ARG1> Confluence Page Id (if not specified, title will be used to find page.)
-t, --title <ARG1> Confluence Page Title (defaults to hostname:filename)
-q, --query <ARG1> Query used to find Confluence Page. Default to title
-m, --macro <ARG1> Macro type that file content is wrapped in (html, panel, code) ("code" by default)
-l, --labels <ARG1> Add page labels. Comma separated. (multiple)
A little later we'll go over some examples.
Confwatch Usage
confwatch will monitor files for changes and upload them to Confluence. Internally confwatch uses confdoc.
confwatch [--verbose] [--add <file>] [--remove <file>] [--list] [--watch]
The following options are supported:
-v, --verbose Verbose output
-c, --config <ARG1> Configuration File (defaults to ~/.confdoc)
-w, --watch Watch files
-a, --add <ARG1> Add file (multiple)
-r, --remove <ARG1> Remove file (multiple)
-l, --list List watched files
-f, --force Force upload of all files now
Setup
Unlike confdoc, confwatch requires a configuration file. This can be specified via the --config parameter otherwise the the default file ~/.confdoc is used if it exists. Details of the configuration file are discussed later.
Watching Files
Before using confwatch, make sure you can successfully upload files using confdoc.
Lets say you want to monitor these files for changes:
- /etc/my.cnf
- /etc/httpd/conf/httpd.conf
confwatch --add /etc/my.cnf --add /etc/httpd/conf/httpd.conf
This just adds them to the list of files that confwatch will monitor. To actually monitor the files:
confwatch --watch
Or prehaps add something similar to this to /etc/rc.local (or equivalent)
confwatch --watch > /var/log/confwatch.log &
Now whenever one of the watched files changes it will be uploaded to Confluence.
confwatch will update the configuration file with the watched files.
In-file Usage
You can add tags to files to override the above arguments. This helps make uploading files easier. We'll cover tags in more detail in the examples section.
Supported tags are
##Title: <string>
##Query: <string>
##SpaceKey: <string>
##Macro: <string>
##PageId: <int>
##ParentId: <int>
##Labels: <string, string, ...>
The Tag Prefix (##)
The above examples prefix tags with ##. The tag prefix is actually any two identical characters. So you just use whatever the file's comment syntax is twice, with an optional space. For instance:
An SQL File
-- Title: My SQL File
-- ParentId: 323423
...
Or an INI file:
;;Title: My INI File
;;ParentId: 241234
...
Configuration Files
The configuration file is optional for confdoc because all parameters can be specified on the command line. For confwatch a configuration file is required.
You can specify a configuration file with the --config parameter.
If --config is not specified and the file ~/.confdoc exists, it is used (This feature is only supported in NodeJS 4.1.0+).
The configuration file must be valid JSON.
The following properties are supported:
{
"server": "http://myconfluenceserver.com",
"spaceKey": "mySpaceKey",
"parentId": "12345",
"username": "myusername",
"password": "myPassword",
"timeout": 60,
"watch": []
}
timeout is used by confwatch only. After a watched file is changed, this is the time in seconds before the file is uploaded to Confluence. Any change to the file within this time will reset the timer. This means you can perform an edit-save-test-edit-save-test cycle without incurring multiple uploads to Confluence.
Remember that parentId is only relevant when a new Confluence Page is created.
watch is an array of absolute files monitored by confwatch. confwatch --add and confwatch --remove update this array.
Confdoc Examples
The examples assume we are executing the commands on a host called myhost.com.
Example 1
The following command will create (or update) a page called myhost.com/etc/httpd/conf/httpd.conf in the root of the Confluence Space with key CONF.
confdoc --server http://myconfluenceserver.com --username myusername --password mypassword --spaceKey CONF /etc/httpd/conf/httpd.conf
Example 2
The next example will update the page with id 12333 in space CONF. This page must exist.
confdoc --server http://myconfluenceserver.com --username myusername --password mypassword --spaceKey CONF --pageId 12333 /etc/httpd/conf/httpd.conf
Example 3
This example will create or update a page in space CONF, under the page with id 12344. The page title will be set to "My Apache Config", and will be labeled with apache and myhost.
confdoc --server http://myconfluenceserver.com --username myusername --password mypassword --spaceKey CONF --title "My Apache Config" --parentId 12344 --labels "apache, myhost" /etc/httpd/conf/httpd.conf
Here is the same example using comment tags in the head of /etc/httpd/conf/httpd.conf
##Title: My Apache Config
##SpaceKey: CONF
##ParentId: 12344
##Labels: apache, myhost
...
...
... rest of apache config file ...
...
...
Then:
confdoc --server http://myconfluenceserver.com --username myusername --password mypassword /etc/httpd/conf/httpd.conf
Files are wrapped in Confluence Marcos
The content file (that is the file passed into confdoc) is added to a Confluence Page using a {code}, {panel} or {html} macro as defined by the --macro parameter. If not specified, a {code} macro is used by default. The title of the macro is the content file plus a time stamp and the md5 hash of the content, Eg "/etc/httpd/conf/httpd.conf (2015-09-23, 6:45:42am) {4ae537c279fee9d1ec8c2d6fd67e09ac}". For html macros, a comment is added to the top the macro with the title in it (because the macro does not support a title).
When updating a page, confdoc looks for a {code}, {html} or {panel} macro with a title matching the file name of the content file. If a matching macro is found, it is updated. Otherwise a new macro is appended to the page. This means you can add your own content to the Confluence Page and it will be preserved.
{html} macro note To use html macros, you need to enable them in Confluence because they are disabled by default. See here for instructions on enabling the HTML Macro.
Free Versioning & Differentials!
Well, it comes with Confluence. When you upload and update your config files in Confluence you can take advantage of Confluence's Page revisions to track changes to your configuration files over time.
FAQs
Will confdoc modify my files?
No. confdoc never modifies the input file.
How do I use confdoc to add tags (eg ##Title) to my input files?
You need to edit your files manually and add the tags yourself. confdoc never modifies your files.
I'm getting an error "Not Found"
Check your Confluence Server URL. Use the --verbose option to get a more detailed error message. It will likely mention a 404 status.
I'm getting an error. What can I do?
Use the --verbose option. This can help output more verbose error messages.
How do I find a Page's Id for use with --parentId or --pageId?
Edit the page in Confluence. The Page Id is in the address bar.
