I’m Zach Davis, principle at Cast Iron Coding, a web development studio in Portland, Oregon. My team and I are responsible for UX design, visual design, and development of Manifold over the course of the grant, and it is my hope that I’ll be able to post regular updates here detailing development and design decisions, challenges, and milestones over the course of the project.
For now, however, I’d like to walk through the technology stack we’ve settled on, and the reasoning behind some of these choices. If anyone has any questions, please don’t hesitate to post a comment!
Where to find the source code
As you know, one of the requirements of the grant funding this development is that Manifold be released as open source, and our current plan is to release Manifold under the GPLv3. For the time being, Manifold source code is stored in the ManifoldScholar/manifold Github repository. If you look at the ManifoldScholar GitHub organization, you’ll see additional repositories for Manifold-API and Manifold-Client. Eventually, we hope to be able to provide the Manifold API as a stand-alone piece of software that can be used to parse, store, and expose ePub and Markdown documents over a RESTful API. In preparation for this, we’re using a git subtree-split strategy to break the Manifold project into separate API and Client packages. These split repositories are updated significantly less frequently than the main Manifold repository. If your goal is to follow our development, for now your best bet will be to just watch the primary repository.
We’ve already made significant progress on Manifold, although we’re still far from an alpha release. We’d love it if you’d show your support for our project by starring our GitHub repo and keeping an eye on development. As we get closer to a stable alpha release in 2016, we’ll invite community members to download and install their own instance of Manifold.
Manifold is split into the client application, and the server-side application. For now, these two applications share a repository to simplify development, but they are very distinct and meant to run independently of each other.
The server side application exposes a REST style API to be consumed by the client. This API conforms to the style and conventions laid out by Steve Klabnik, Yehuda Katz, Dan Gebhardt, Tyler Kellen, and Ethan Resnick in the JSON API Specification. While it’s important that developers expose all the things with APIs, it’s challenging when each API follows its own idiosyncratic conventions. One of our goals on this project is to make Manifold as easy as possible to integrate into a presses existing infrastructure and environment, and following an established API specification helps us with that goal. Because the Manifold client application consumed Manifold’s public API, integrators can be sure that the API is well tested and reliable.
Authentication against the API will be handled using JSON Web Tokens (JWT). It will also be possible for a user to generate an API token by logging in through an OAuth provider such as Twitter or Facebook.
The advantages to the SPA approach are, well, manifold. The application will feel very fast, and we’ll be vastly reducing the amount of data that’s sent over the network. Complex UI elements, like the annotation pieces, will be have a much more stable, testable framework backing them. There will be more room for reusable components, and the various state-changes that can occur in the client-side application will be well tested.
While we’re diving in head-first on React + Redux, we are not, for now, following the current trend of doing only inline-CSS. For the time being, we’ll be using the SASS preprocessor for all styles.
We rely heavily on NPM for package management, and Webpack for transpiling assets during development, and for building assets for production. At Cast Iron, we’ve used Grunt and Gulp on other projects, but it looks to us like the React community is gravitating toward Webpack, and for good reasons. On Manifold, it’s being used for automatically linting our code, for generating icon fonts from SVG icons, for transpiling ES6+ to ES5, and Sass to CSS.
Tests are important. They build confidence and help us to refactor without regressions. While we don’t always follow test-driven-development practices, we do feel that it’s important to have a robust test suite in place. On the API side, we’re using rspec for tests. On the client-side we will be using Mocha.
Server infrastructure and continuous integration
DevOps and infrastructure automation are essential to our workflow at Cast Iron. We use Boxen to setup development instances of projects, and we use Puppet to deploy applications to staging and production environments. Our manifests for deploying Manifold are still in progress, but they’re close. Soon, I hope to have a staging environment that’s updated regularly via Jenkins, our continuous integration server. Soon, we’ll also have Travis build notifications in place on the Github repository.
To run Manifold, you’ll need to have the following setup on a server:
- Nginx for serving the Ruby app and the Node app
- Puma for serving Manifold API (although you could use Unicorn or another app server)
- Ruby 2.2.x
- Postgres for the API database
- A recent version of Node
- Eventually, I expect you’ll need Elastic Search for the search component
We’ll be providing instructions on how to set this up, as well as sample config files. Eventually, I hope to provide apt-get packages for Ubuntu as well. Once things are a bit more stable, we’ll regularly release docker containers that you can use to take Manifold for a spin.
Hopefully this gives you a better sense of what we’re using to build Manifold, and why. I’d love to have a conversation about our choices, so please don’t hesitate to leave feedback in the comments. In the coming weeks, I’m going to try to share some early artifacts from the UX and visual design process, to give you a better sense of what Manifold will look like and what it will be capable of.