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 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 --username --password [--config ] [--spaceKey ] [--parentId ] [--pageId ] [--title ] [--query <string>] [--labels <labels>] [--macro <macro>] [--quiet] [--noupgrade] <input_file><br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />The following options are supported:<br /> -e, --quiet Suspress non-error output<br /> -v, --verbose Verbose output and full error messages<br /> -n, --noupgrade Suspress new version check<br /> -c, --config <ARG1> Configuration File (defaults to ~/.confdoc)<br /> -s, --server <ARG1> Confluence Server URL<br /> -u, --username <ARG1> Confluence Username<br /> -p, --password <ARG1> Confluence Password<br /> -f, --force Force page update even if no change in content<br /> -k, --spaceKey <ARG1> Confluence Space Key<br /> -o, --parentId <ARG1> Confluence Parent Page Id (when creating new page. Space root used if not specified)<br /> -i, --pageId <ARG1> Confluence Page Id (if not specified, title will be used to find page.)<br /> -t, --title <ARG1> Confluence Page Title (defaults to hostname:filename)<br /> -q, --query <ARG1> Query used to find Confluence Page. Default to title<br /> -m, --macro <ARG1> Macro type that file content is wrapped in (html, panel, code) ("code" by default)<br /> -l, --labels <ARG1> Add page labels. Comma separated. (multiple)<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />A little later we'll go over some examples.</p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">Confwatch Usage</h2></p><p class="my-3"></code>confwatch<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> will monitor files for changes and upload them to Confluence. Internally confwatch uses confdoc.</p><p class="my-3"></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />confwatch [--verbose] [--add <file>] [--remove <file>] [--list] [--watch]<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />The following options are supported:<br /> -v, --verbose Verbose output<br /> -c, --config <ARG1> Configuration File (defaults to ~/.confdoc)<br /> -w, --watch Watch files<br /> -a, --add <ARG1> Add file (multiple)<br /> -r, --remove <ARG1> Remove file (multiple)<br /> -l, --list List watched files<br /> -f, --force Force upload of all files now<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3><br />Unlike </code>confdoc<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">, </code>confwatch<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> <strong>requires</strong> a configuration file. This can be specified via the </code>--config<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> parameter otherwise the the default file </code>~/.confdoc<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> is used if it exists. Details of the configuration file are discussed later.</p><p class="my-3"><h3 class="text-lg font-medium mt-4 mb-2">$3</h3><br /><strong>Before using </code>confwatch<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">, make sure you can successfully upload files using </code>confdoc<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">.</strong></p><p class="my-3">Lets say you want to monitor these files for changes:<br />* /etc/my.cnf<br />* /etc/httpd/conf/httpd.conf</p><p class="my-3"></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />confwatch --add /etc/my.cnf --add /etc/httpd/conf/httpd.conf<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />This just adds them to the list of files that </code>confwatch<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> will monitor. To actually monitor the files:<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />confwatch --watch<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />Or prehaps add something similar to this to /etc/rc.local (or equivalent)<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />confwatch --watch > /var/log/confwatch.log &<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />Now whenever one of the watched files changes it will be uploaded to Confluence.<br /></code>confwatch<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> will update the configuration file with the watched files.</p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">In-file Usage</h2></p><p class="my-3">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.</p><p class="my-3">Supported tags are<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />##Title: <string><br />##Query: <string><br />##SpaceKey: <string><br />##Macro: <string><br />##PageId: <int><br />##ParentId: <int><br />##Labels: <string, string, ...><br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">The Tag Prefix (##)</h2></p><p class="my-3">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:</p><p class="my-3">An SQL File<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />-- Title: My SQL File<br />-- ParentId: 323423<br />...<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3">Or an INI file:<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />;;Title: My INI File<br />;;ParentId: 241234<br />...<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">Configuration Files</h2></p><p class="my-3">The configuration file is optional for </code>confdoc<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> because all parameters can be specified on the command line. For </code>confwatch<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> a configuration file is required.</p><p class="my-3">You can specify a configuration file with the </code>--config<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> parameter. </p><p class="my-3">If </code>--config<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> is not specified and the file </code>~/.confdoc<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> exists, it is used (<strong>This feature is only supported in NodeJS 4.1.0+</strong>). </p><p class="my-3">The configuration file must be valid JSON. </p><p class="my-3">The following properties are supported:</p><p class="my-3"></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />{<br /> "server": "http://myconfluenceserver.com",<br /> "spaceKey": "mySpaceKey",<br /> "parentId": "12345",<br /> "username": "myusername",<br /> "password": "myPassword",<br /> "timeout": 60,<br /> "watch": []<br />}<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><em>timeout</em> is used by </code>confwatch<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> 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.</p><p class="my-3">Remember that <em>parentId</em> is only relevant when a new Confluence Page is created.</p><p class="my-3"><em>watch</em> is an array of absolute files monitored by </code>confwatch<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono">. </code>confwatch --add<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> and </code>confwatch --remove<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> update this array.</p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">Confdoc Examples</h2></p><p class="my-3">The examples assume we are executing the commands on a host called myhost.com.</p><p class="my-3"><strong>Example 1</strong></p><p class="my-3">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.<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />confdoc --server http://myconfluenceserver.com --username myusername --password mypassword --spaceKey CONF /etc/httpd/conf/httpd.conf<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><strong>Example 2</strong></p><p class="my-3">The next example will update the page with id 12333 in space CONF. This page must exist.<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />confdoc --server http://myconfluenceserver.com --username myusername --password mypassword --spaceKey CONF --pageId 12333 /etc/httpd/conf/httpd.conf<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><strong>Example 3</strong></p><p class="my-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.<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />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<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />Here is the same example using comment tags in the head of /etc/httpd/conf/httpd.conf<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />##Title: My Apache Config<br />##SpaceKey: CONF<br />##ParentId: 12344<br />##Labels: apache, myhost<br />...<br />...<br />... rest of apache config file ...<br />...<br />...</p><p class="my-3"></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />Then:<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"><br />confdoc --server http://myconfluenceserver.com --username myusername --password mypassword /etc/httpd/conf/httpd.conf<br /></code>`<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"></p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">Files are wrapped in Confluence Marcos</h2><br />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 </code>--macro<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> 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).</p><p class="my-3">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.</p><p class="my-3">!<a href="https://raw.githubusercontent.com/garyns/confluence-config-documentator/master/doc/conf1.jpg" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">Conf1</a></p><p class="my-3"><strong>{html} macro note</strong> To use html macros, you need to enable them in Confluence because they are disabled by default. <a href="https://confluence.atlassian.com/doc/html-macro-38273085.html" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">See here for instructions on enabling the HTML Macro</a>.</p><p class="my-3"><br /><h2 class="text-xl font-semibold mt-5 mb-3">Free Versioning & Differentials!</h2></p><p class="my-3">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.</p><p class="my-3"><h2 class="text-xl font-semibold mt-5 mb-3">FAQs</h2></p><p class="my-3"><strong>Will confdoc modify my files?</strong></p><p class="my-3">No. confdoc never modifies the input file.</p><p class="my-3"><strong>How do I use confdoc to add tags (eg ##Title) to my input files?</strong></p><p class="my-3">You need to edit your files manually and add the tags yourself. confdoc never modifies your files.</p><p class="my-3"><strong>I'm getting an error "Not Found"</strong></p><p class="my-3">Check your Confluence Server URL. Use the </code>--verbose<code class="bg-muted px-1 py-0.5 rounded text-sm font-mono"> option to get a more detailed error message. It will likely mention a 404 status.</p><p class="my-3"><strong>I'm getting an error. What can I do?</strong></p><p class="my-3">Use the </code>--verbose` option. This can help output more verbose error messages.</p><p class="my-3"><br /><strong>How do I find a Page's Id for use with --parentId or --pageId?</strong></p><p class="my-3">Edit the page in Confluence. The Page Id is in the address bar.<br />!<a href="https://raw.githubusercontent.com/garyns/confluence-config-documentator/master/doc/conf2.jpg" class="text-primary hover:underline" target="_blank" rel="noopener noreferrer">Conf2</a></p></div><div class="flex justify-center absolute inset-x-0 bottom-0 bg-gradient-to-t from-background via-background to-transparent pb-4 pt-16"><button data-slot="button" class="inline-flex items-center justify-center whitespace-nowrap text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50 h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-chevron-down mr-1 h-4 w-4"><path d="m6 9 6 6 6-6"></path></svg>Show more</button></div></div></div><template id="P:3"></template><template id="P:4"></template></div></div></div><script>self.__next_f.push([1,"29:[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}]\n2a:[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^1.1.2\"}]\n2b:[\"$\",\"$L5\",\"md5\",{\"href\":\"/package/md5\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"md5\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^2.0.0\"}]]}]\n2c:[\"$\",\"$L5\",\"moment\",{\"href\":\"/package/moment\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"moment\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^2.10.6\"}]]}]\n2d:[\"$\",\"$L5\",\"selfupdate\",{\"href\":\"/package/selfupdate\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"selfupdate\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^1.1.0\"}]]}]\n2e:[\"$\",\"$L5\",\"stdio\",{\"href\":\"/package/stdio\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"stdio\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^0.2.7\"}]]}]\n2f:[\"$\",\"$L5\",\"superagent\",{\"href\":\"/package/superagent\",\"className\":\"group flex items-center justify-between rounded-md px-2 py-1.5 text-sm transition-colors hover:bg-accent\",\"children\":[[\"$\",\"span\",null,{\"className\":\"flex items-center gap-1.5 truncate font-mono text-foreground\",\"children\":[[\"$\",\"svg\",null,{\"ref\":\"$undefined\",\"xmlns\":\"http://www.w3.org/2000/svg\",\"width\":24,\"height\":24,\"viewBox\":\"0 0 24 24\",\"fill\":\"none\",\"stroke\":\"currentColor\",\"strokeWidth\":2,\"strokeLinecap\":\"round\",\"strokeLinejoin\":\"round\",\"className\":\"lucide lucide-chevron-right h-3 w-3 text-muted-foreground opacity-0 transition-opacity group-hover:opacity"])</script><script>self.__next_f.push([1,"-100\",\"children\":[[\"$\",\"path\",\"mthhwq\",{\"d\":\"m9 18 6-6-6-6\"}],\"$undefined\"]}],\"superagent\"]}],[\"$\",\"span\",null,{\"className\":\"ml-2 shrink-0 font-mono text-xs text-muted-foreground\",\"children\":\"^1.4.0\"}]]}]\n"])</script><div hidden id="S:3"><div data-state="inactive" data-orientation="horizontal" role="tabpanel" aria-labelledby="radix-_R_aav5ubrb_-trigger-dependencies" hidden="" id="radix-_R_aav5ubrb_-content-dependencies" tabindex="0" data-slot="tabs-content" class="flex-1 outline-none mt-6"></div></div><script>$RS=function(a,b){a=document.getElementById(a);b=document.getElementById(b);for(a.parentNode.removeChild(a);a.firstChild;)b.parentNode.insertBefore(a.firstChild,b);b.parentNode.removeChild(b)};$RS("S:3","P:3")</script><div hidden id="S:4"><div data-state="inactive" data-orientation="horizontal" role="tabpanel" aria-labelledby="radix-_R_aav5ubrb_-trigger-versions" hidden="" id="radix-_R_aav5ubrb_-content-versions" tabindex="0" data-slot="tabs-content" class="flex-1 outline-none mt-6"></div></div><script>$RS("S:4","P:4")</script><script>$RC("B:1","S:1")</script></body></html>