Unified ReadTheDocs Documentation

SubutaiWarDog is OptDyn CTO and Founder Alex Karasulu

Documentation! It’s unfortunately the neglected “red-headed step child” of developers. Most people don’t get it: a product is useless without solid documentation. Even to this day, most of our developers avoid documenting. “Dude, the code documents everything,” they say. To change the mindset, we need to avoid barriers and make authoring content a pleasure.

Documentation Dilema

I personally love documenting. Even before I start working on a new idea or writing code. It helps get your thoughts together. Authoring documents should be pleasant and effortless for all authors, whether you’re an engineer writing technical specifications for fellow developers or writing product manual for end users.

Documentation started turning into a thorn in our side when it came time to organize all the documents we haphazardly produced over years of working on the Subutai Platform. It stopped being a joy and quickly turned into a headache. Information about the project was spread all over. Some information silos were not easily accessible especially to those outside of engineering. Management wanted Google Docs and refused to use GitHub where most of our developer community used Markdown on our project wiki’s. Practically no one (minus the die hards) wanted to touch the restructureText in our ReadTheDocs content committed to git repositories (these were even less accessible to management). At least the GitHub Wiki pages could be edited by non-engineering staff using the convenient editor GitHub provides, but still we could not please everyone, and no one was happy about the documentation situation.

To make matters worse, in addition to the aim of unifying and organizing all these documents, we were pressed to provide a smooth user experience between our website and our documentation. Meaning visitors should not have any sense of discontinuity while going back and forth from the website through links between our documentation and the main website’s content.

Bringing it Together

Looking for a solution, we naturally googled around and ran into this sweet blog post from Rob Day, Good documentation, ReadTheDocs and Markdown. It got us thinking and was a pleasure to read while seeing what others were doing to unify their documentation. Rob clearly showed that some custom scripting was unavoidable.

Unlike the Clearwater Project, we wanted to unify our markdown documents in GitHub project wikis and Google Docs. We also realized we’re going to have to modify the ReadTheDocs theme in order to make the user experience more fluid. We wanted a thin website, without requiring many changes to it over time. We wanted users to fluidly go back and forth from the ReadTheDocs content generated from Google Docs and Wiki Markdown content which both our non-technical and engineering staff can easily author and maintain.

Google Drive: /readthedocs Folder

We started by defining a global table of contents and the boundaries where developer documentation crosses over to non-technical content. We also created a root folder in Google Drive for the documentation team called /readthedocs. General project information, community content, and resources were put into their own top level sections: General, Community, and Resources. Folders of the same name under the /readthedocs folder were created for these categories. Word docx documents in these folders are downloaded and converted into restructuredText then added to the toctree automatically based on their position.

GitHub Wiki Submodules

We presumed the technical content to be resident in the GitHub project wikis. We setup the Subutai readthedocs GitHub project to import all the sub-project wikis. See all the modules imported here. The project wiki markdown is converted into restructuredText and added to the Projects of the entire documentation site.

We even added some extra organizational features like automatically generating side bar files (_Sidebar.md) for the GitHub wiki if users tag pages with a PARENT_PATH attribute in HTML comments at the end of the markdown page like so:

ORIGIN: github

The comment is hidden but parsed by the documentation system to generate the side bar and commit it back to the wiki git repo. This way the content can be neatly organized with minimal effort in the GitHub Wiki which is mirrored also in the organization of the generated ReadTheDocs content: i.e. look at the side bar of the PeerOS Agent Wiki and the ReadTheDocs documentation generated for the Agent Project.

Custom ReadTheDocs Theme

For the finishing touches, we added a custom Subutai RTD Theme to mirror the Subutai Website menus so back and forth navigation was seamless. Notice also, the blog you’re reading this article from follows the same pattern to facilitate back and forth navigation.


It was a headache to organize and script out all the toctree generation, the markup and docs transformations for everything to work. But it was all worth it. Not only is everything really nicely organized. We can now search all our documentation from one place. Plus the fluid visitor experience using custom RTD theme made it pretty.

Changes to any wiki pages or Google document automatically download, convert, and deploy to keep the unified website and documentation synchronized. Take a look and see the seamless experience for yourself on the Subutai Website and the Subutai ReadTheDocs Documentation Site.

Next up our community wants to make product online help use it. Mike and Dilshat already started writing a Slack bot to help people on our community Slack. Toight!

If you’re interested in setting up the same unified scheme for your own project feel free to fork our readthedocs repository. Here’s our readthedocs documentation for the readthedocs project. Yeah, that sounds funny: we know. Happy documenting!

Welcome Blockchain-in-a-Box, the latest addition to the Subutai family of blueprints!

By Sally Khudairi, with Alex Karasulu and Lars Bøgild Thomsen.

Blueprints are quickly changing the process of application development and deployment —and the Subutai Blockchain-in-a-Box blueprint can take you from concept to executing Ethereum Smart Contracts in minutes.

Alex Karasulu (CTO and Founder of OptDyn, makers of Subutai) explains what makes blueprints so great:

Blueprints just rock! Users deploy an application at the press of a button into an existing or new environments. Subutai Blueprints let authors define an application once, and only once! Never do they have to go through defining it again. Plus authors can publish blueprints on the Subutai Bazaar so others can launch them with a button press. You can make serious amounts of GoodWill by publishing a tight blueprint. Minecraft server anyone? Hint hint …

The utility of the blueprints becomes most evident with the Blockchain-in-a-Box blueprint. It builds out an entire Solidity development environment with a private (or public) dedicate blockchain. It’s instant Blockchain-as-a-Service with steroids to get the developer going and fast. I hated having to deal with different versions and conflicts between Geth, Truffle … and all the other tools. What a pain to also deal with the infrastructure. When I need to go to town on a new contract I just fire up a new environment. The nice part is I can access my environment to continue developing from anywhere on any one of my machines at home or on the go.

Seriously though, when designing the blueprint feature, we wondered if we should take the Dockerfile approach, but then saw we need more power for proper devops and flexibility based on user needs. Blueprints had to be idempotent to perpetually update applications as environments change. Why reinvent the wheel right? We already have templates for containers, so the blueprint needed much more than a Dockerfile for templating a single host. It had to describe an entire application stack in a distributed P2P environment.

Personally I love the patterns Vagrant uses. I wanted blueprints to be like (more declarative) Vagrantfiles for entire virtual private cloud environments and application stacks. I dreamed of being able to do something like this:

`vagrant up`

And have it provision my blueprint right there and then like I do for single virtual machines using vagrant. Then I thought, “heck why not just do exactly that. We can write a Vagrant Plugin for Subutai.”

Well that day has come and it is glorious. So in any folder containing a Subutai.json blueprint, just run the command above to provision, meaning, build out that entire environment in a single virtual machine serving as a local or hub connected peer. This means you can check out projects from the GitHub having a Subutai.json file to launch an entire P2P cloud environment with a ready to go stack. The same blueprint can be exposed on the Subutai Bazaar for your projects. The Bazaar has GitHub integration that allows you to launch environments using your own blueprints, and version them. You can publish your blueprints on the Products page at the Bazaar too so others can use them as well.

So blueprints not only work inside the Bazaar, but they work with awesome developer and sysadmin tools like Vagrant. Next week we’ll be releasing our Ansible Module for Subutai specifically for system administrators to deploy armies of remote peers at the press of a button. In the meantime, everyone is welcome to sign up at our Blueprint Hackathon where all paricipants get GoodWill and prizes for blueprints. Feel free to PR us with your favorite application to add to the wish list of application blueprints for the hackathon. We have great docs (RTD integrated into our Website), and our community is ready to help out on our Slack if you have any questions.

Just last week, Alex imagined bringing Blockchain-as-a-Service (BaaS) functionality to blueprints with an all-inclusive developer environment for writing Solidity Smart Contracts and testing them on a private Ethereum network…and the idea for Blockchain-in-a-Box was launched.

With Alex’s vision on the board, OptDyn Senior Engineering Lead Lars Bøgild Thomsen began to design the blueprint. Mere days later, Blockchain-in-a-Box was born!

Here Lars describes the process on how to get started using just a browser and an Internet connection.

The hardest part? Waiting for the initial build —after all, this is an entire desktop system in a container. Once that’s complete, you’re on your way to writing Dapps in minutes! To quote Lars, this is possible “Only with Subutai!” [Watch Lars’s walkthrough below]

We hope you enjoy Subutai blueprints as much we do, and look forward to hearing your success on the Subutai Slack. Happy building!

Follow @Subutai_KHAN and stay tuned to the latest news from the horde.

# # #

Big Changes for Subutai

SubutaiWarDog is OptDyn CTO and Founder Alex Karasulu. 

We finally did it! Watching so many ICOs successfully complete on grandiose ideas, vaporware, or merely prototypes we decided to commit and conduct our own token distribution event for Subutai’s KHAN™.

With a sum total of over a century in Open Source, as recognized, and trusted leaders in the community, none of us wanted anything to do with an ICO at first. We are still prudent and think the SEC should apply more antibiotics to protect people. The  negative stigma kept us away. Even though we were certain to be successful, we thought it was shady, and have reputations to uphold.

We could have launched early with Subutai’s PeerOS and the Subutai Bazaar being mature and robust now in their sixth major versions. Watching Golem raise 8.4M USD in 29 minutes intrigued us. The final trigger was the completion of the Subutai Blockchain Router 2.0 design which mines Ether, and hence Ethereum Blockchain based mine-able tokens. With manufacturing underway we thought it was finally time.

The parameters of the token distribution event for Subutai’s currency, the KHAN™, is not yet available at this time. We’re working with Vanbex to quickly ramp things up. Stay tuned for the dates and all the token parameters. In preparation, we’ve organized our documentation, revamped the subutai.io website, and published our Executive Summary of the ICO whitepaper. We’re excited to get feedback from our user community (the horde!) and to make sure the token mechanics evolve through community participation.

Recent changes included a rename of the Hub to the Bazaar along with several new features and improvements across the platform. The tray application has also been renamed to the Subutai Control Center. A new convenient file transfer feature has been added as well as and Desktop-as-a-Service feature. Users can now remote desktop to containers with a desktop installed and x2go. We’ve added application blueprints for WordPress, and Mattermost.

Perhaps the most attractive application blueprint is our just released Blockchain-in-a-Box, which offers a private blockchain with a full development and test environment for Solidity Smart Contracts (available now on the Bazaar!). Over the next few releases you’ll see more new features that will make the P2P cloud irresistible.

We invite everyone to get involved. Register below for our newsletter to get advanced notice of our ICO and new features on the platform. Sign up to the Subutai Bazaar, install your own peer and participate in the P2P cloud economy. Let’s conquer the cloud together!

Keynote by Jon “maddog” Hall at Latinoware 2017: “The Grand Slam for Latin America”

Screenshot 2018-02-17 at 21.05.44

For those who are unable to watch Open Source educator/evangelist and OptDyn CEO Jon “maddog” Hall’s “The Grand Slam for Latin America” keynote at Latinoware 2017 https://youtu.be/P4GTwfg_1c4 , below is the full transcript:

I apologize that we don’t have any slides for you to see but there isn’t too much to see on the slides anyway so I will paint the picture for you to see in your mind. Sometimes that’s better anyway.

I am Jon “maddog” Hall. I am Chief Executive Officer of a company called OptDyn. I’ve been in the free software space a very long time.

Down there, aiming the camera, is my Chief Technical Officer, Alex Karasulu: “wardog@optdyn.com”

Beside being Chief Executive Officer for OptDyn, I am also the Board Chairman of the Linux Professional Institute, of which Cesar, who has been entertaining you, is the Director of Operations here in Latin America. I am also the President of Project Cauã, which is a project to help university students make money and start their own company while they are in university.

Continue reading → Keynote by Jon “maddog” Hall at Latinoware 2017: “The Grand Slam for Latin America”

Calling all Developers, Sysadmins, and Enthusiasts for the Subutai Blueprint Hackathon


OptDyn, makers of the Subutai Open Source Peer-to-Peer Cloud Computing platform, invite developers and system administrators at all levels to participate in the Subutai Blueprint Hackathon.

WHAT: The Subutai Blueprint Hackathon is an international event across the globe to develop application blueprints for the P2P Cloud Crowd, the Subutai Horde. Hackathon participants earn GoodWill, the digital asset used to exchange resources, with every Subutai Blueprint they create and share on the Subutai Bazaar.

WHAT IS A BLUEPRINT? Subutai Blueprints specify general instructions for installing, updating and maintaining P2P distributed cloud applications. The Subutai P2P Cloud combines these instructions with load and resource availability information to optimally place infrastructure resources in P2P cloud environments and run distributed applications. P2P orchestration can occur perpetually to adapt to shifting conditions to keep applications running.

Continue reading → Calling all Developers, Sysadmins, and Enthusiasts for the Subutai Blueprint Hackathon