Think of a repository where you are able to consume knowledge that someone shared as well as understand how it works. Does GitHub come to mind? What if you could do the same thing with deployment automation? ElasticBox boxes are your GitHub equivalent for sharing, running, and explaining deployment automation code.
A box wraps application lifecycle configuration along with documentation in the form of a README, which explains the structure, purpose, the way it works and what it requires for a successful deployment. Think of how many documents go unread because they are available in full-featured content management solutions far removed from the scene of action. Whereas, a README allows DevOps to explain software lifecycle automation right where developers consume it.
Here’s an example Kibana box that deploys and manages the Kibana application lifecycle to visualize and consume Logstash event data. The README is the first thing you see in the box. It explains Kibana, tells you what environments are compatible and what values you can customize when deploying.
In this way, READMEs give developers, QA, and DevOps just the context they need to kickstart deployments. Their collaboration follows organically. When experts share automation and relevant information in box READMEs, they promote better understanding among teams and lower the friction for adopting newer and better technology throughout the enterprise.
Devops specialized in their respective fields like Puppet automation can define application deployments and at the same time help others to understand them. Enterprises gain specific benefits from using the box collaboration and READMEs:
- DevOps can easily explain new technology within a deployment context to drive adoption across engineering teams.
- Well understood and documented automation makes people far more apt to trust and consume it.
- New or junior DevOps and developers can self-train and familiarize with technologies much faster without the overhead of training costs.
- IT decision makers get a transparent view of the operational complexity required to power technology stacks so that they can realistically plan for business expansion or budget roadmaps.
Now that we understand the overall effectiveness of box READMEs, how to write one? Go to any of your boxes in the catalog and edit (using pencil icon) the Overview section. That’s the README. It follows a markup language called Markdown. Here’s some basic syntax from the Markdown library to describe a README.
Paragraphs, headers, and blockquotes
Write a paragraph as you would in any typical text editor but without indenting with spaces or tabs.
Markdown offers two styles to identify headings: Setext and atx. Setext-style headers for HTML <h1> and <h2> levels are created by “underlining” with equal signs (=) and hyphens (-), respectively.
To create an atx-style header, you put 1-6 hash marks (#) at the beginning of the line — the number of hashes produces the desired HTML header.
Blockquotes require using email-style ‘>’ angle brackets.
Markdown uses *asterisks* and _underscores_ to emphasize information.
Unordered (bulleted) lists use asterisks, pluses, and hyphens (*, +, and -) as list markers. For example:
Ordered (numbered) lists use regular numbers, followed by periods, as list markers. For example:
Use square brackets to define inline links. For example: This is an [example link](http://example.com/).
This is just like the link syntax. For example: ![alt text](/path/to/img.jpg “Title”)
Span code snippets by wrapping them in backtick quotes.
For a more complete README syntax guide, see the Markdown reference.
Sample README markdown to explain a MongoDB deployment
# What is MongoDB? MongoDB (from humongous) is a cross-platform document-oriented database. Classified as a NoSQL database, MongoDB eschews the traditional table-based relational database structure in favor of JSON-like documents with dynamic schemas (MongoDB calls the format BSON), making the integration of data in certain types of applications easier and faster. Released under a combination of the GNU Affero General Public License and the Apache License, MongoDB is free and open-source software. *** ## Customizing the Deployment with these Variables * **username**: Name of the admin user * **password**: Password of the admin user * **VERSION**: Version to be installed [2.6.1 as default value] * **DB_PATH**: Path where MongoDB will be installed [default as default value] * **LOG_PATH**: Path where MongoDB will store the logs [default as default value] * **mongodb**: Port for mongod and mongos instances [27017 as default value] *** ## Documentation For more help, check out MongoDB’s [Documentation](http://docs.mongodb.org/manual/). *** ## License ```sh Most MongoDB source files (src/mongo folder and below) are made available under the terms of the GNU Affero General Public License (AGPL). See individual files for details. As an exception, the files in the client/, debian/, rpm/, utils/mongoutils, and all subdirectories thereof are made available under the terms of the Apache License, version 2.0. ```
A successful deployment should not be a sporadic event left to chance. Every deployment can succeed when it follows structured processes and best practices. READMEs empower DevOps to follow good automation practices. A good README allows DevOps specialists to explain how a piece of automation code installs a particular software, what environment it requires, and how users can customize their deployments.
Get a step closer to democratizing software automation configuration and infrastructure as code with the box model and READMEs. They provide the context that bridges the gap between systems, environments, and users. And we’re just getting started. Expect a lot more when you develop automation the right way with box READMEs. Start here in ElasticBox.