This Week in Manifold: DevOps, Infrastructure, and Social Activity

Thanks for joining me for another installation of “This Week in Manifold.”

First off, please accept my apologies for missing last week’s update. When last Friday rolled around, we had a number of updates ready to go out to our staging site. However, when it was time to deploy, we hit a few unexpected problems.

DevOps, Hosting Manifold, and Deployment

This release adds a new metadata field to projects. Because the exact metadata requirements are difficult to pin down and may change from press to press, we wanted a relatively flexible approach to storing project, text, and resource metadata. Back in the day, we might have used an EAV model for this, but there are many well-documented drawbacks to that model. Because Manifold uses PostgreSQL as its database backend, we have access to a variety of field types for storing arbitrary amounts of data. In the past, we’ve used HSTORE for storing key/value pairs, but in this case we wanted something more flexible that could store different data types (HSTORE stores strings, but we want to store integers, boolean values, strings, arrays, etc). Recent versions of PostgreSQL include the JSONB field type, which is exactly what we want in this case.

Alas, that meant that the October 28th release required some infrastructure updates. Sure, we could have shelled into the staging server and done a quick upgrade, but that’s not how we roll on this project. It’s really important to us that it be possible to easily provision hosts for Manifold, which means automating as much as possible. As Manifold grows, it relies on more and more services to run, which makes setting it up increasingly complex. With this release, Manifold needs all of the following configured on the server to run correctly:

  • Ruby 2.3 (for the API)
  • Node 4.5 or higher (for the client)
  • Postgres 9.4 or higher (for storage)
  • Redis (for queuing background jobs)
  • ImageMagick or GraphicsMagick (for resizing images)
  • Nginx or Apache (for serving the API and the Client)

Moreover, in addition to having all these requirements in place, the server also requires that a number of background processes are always running. As of right now, there are four custom services (excluding the webserver and the database server) that need to be running on the host: 1) manifold_api (Rails app served by Puma), 2) manifold_client (Node app), 3) manifold_scheduler (Ruby daemon), and 4) manifold_workers (Sidekiq). Keeping four services running on a server (or on multiple servers) is not without its complexities. If we run these on Ubuntu Trusty (v14), for example, we need Upstart scripts that manage the services. If we run Manifold on Ubuntu Xenial (v16), then we’re going to need Systemd scripts. If it runs on older versions of Centos or Redhat, then we’ll probably need some init.d scripts.

Running a complex app with separate parts is tricky. Internally at Cast Iron, we use puppet and foreman to manage these services. Needing to support Postgres 9.4 got us thinking about deploying Manifold to Ubuntu Xenial, which in turn led us to revisit our manifests. Once we went to Xenial, we had to rewrite our startup scripts for systemd, which in turn revealed problems with how we were storing secrets in the environment. In short, instead of spending the last week working on project resources and feature development, we spent it paying down some technical debt on the infrastructure side, and improving Manifold’s devOps and stability.

That’s done now, and we’re deploying Manifold to Xenial and fully managing its environment and all dependencies via Puppet. Revisiting this infrastructure has also given us an opportunity to reflect further on Manifold’s installation story and continue discussions about how we can make Manifold easy for other presses to adopt and install.

New Features

We did manage to slip a few important features into this week’s release. The full list is below, but there’s one in particular I want to highlight.

This release includes a scheduler that runs constantly in the background while Manifold is running. One of the things this scheduler does is trigger a background job for fetching tweets related to projects in Manifold. That job currently runs hourly.

Editors can use twitter search terms to describe what kind of tweets Manifold should pull in for a given project. This gives editors quite a bit of flexibility. For example, Manifold might watch the author’s twitter account for all tweets with a specific hash tag. Or, it might watch twitter in general for all tweets that include a given hashtag. Our tweet fetching service accepts multiple search terms, so it’s possible for a project to follow multiple accounts and hashtags.

These tweets show up on the project activity feed. Readers can browse through the historical activity for a project and see the events—texts being added, tweets about the project, new resources uploaded—that took place as the project became a published book (see screenshot, below). Our hope is that showing this activity helps make public the iterative aspects of authorship.

Project Activity

Well, that’s enough for today. I’ll be back next week with another update. Enjoy the weekend!


  • Display project “makers” (authors, editors, etc) on one line
  • Improve header/icon lockup on project detail component
  • Refactor ingestion resources into a new model that is distinct from project resources
  • Clean up API binstubs

Features and Improvements

  • Add JSONB metadata field to projects; adjust project import mechanism to include metadata
  • Expose project metadata in API
  • Render project metadata in the client
  • Incorporate Sidekiq for background job processing
  • Add the concept of model ownership in various places. Manifold will now track who creates a project.
  • See a system-level user for ownership purposes
  • First pass at project events subsystem including background event generation; create Event factory class
  • Expose project events via the API
  • Render project events in the “activity” component on the project detail view
  • Add job for queuing the fetching of project tweets
  • Add job for fetching project tweets
  • Add a background scheduler (Clockwork) for triggering recurring background jobs

Tooling and Libraries

  • Update Postgres requirement to 9.4 or 9.5 for JSONB
  • Adjust Travis CI build to use Yarn instead of NPM
  • Feed Travis build notifications to Slack
  • Numerous revisions to deployment configuration

Bug Fixes

  • PropType correction in EventList component
  • Address 1:N queries in the project controller
  • Correct text icon on project texts list
  • Fix padding on coverless project heroes
  • Adjust font size and padding on project makers


Joining Manifold

Happy Halloween!

My name is Jojo Karlin and I am an English doctoral student and Digital Fellow at the Graduate Center, CUNY. I’ve joined Manifold this fall to help get the word out about what the team has been up to, and I am excited to investigate the generative potential built into this iterative, collaborative platform. I love the ways Manifold seeks to enrich scholarly publication by building communities of researchers engaged in collective annotation and networked reading.

When friends and acquaintances unfamiliar with the field hear I work in “digital humanities,” they often react with anxieties about the death of print. Skeptical bibliophiles lament the impact of screens on humanity as they cite popular science articles about babies swiping pages of print books.  Yet I remain a stalwart defender of books in their many forms. I grew up in a house lined with books and have a categorical weakness for library book sales and department book swaps; I also depend on my computer and smartphone as part of my reading practice.

Books, even print-only, are not single-use — people come to them and at them from different angles and at different times. I believe that the many ways we read books should be simultaneously available and that ideas deserve the full range of available outlets and expression. What I particularly love about Manifold is the way it bridges print and digital forms, giving presses and authors the opportunity to benefit from affordances of both — utilizing digital features while reinforcing the value of print-based scholarship.

Since joining Manifold, I have begun to see how the team approaches the transformations of text in recent years, the influx (sometimes numbing inundation) of social media, and the existing endeavors of numerous presses to engage scholarship digitally. “Building Manifold” gives me a sense of Manifold’s dual purpose– platform construction and conceptual restructuring — and Zach’s updates describe incremental decisions of development. By taking pains to publicly share the process of creating the tool, the Manifold team participates in the kind of transparent teamwork that the tool itself proposes. I look forward to sharing my perspective as well.

In the coming months, I will help to surface some of the exciting progress that the team has been making. I will post updates about design, interviews with team members, and reflections on some of the trickier conceptual decisions. Even jumping in now, I have found the whole team — Susan, Zach, Matt, Doug, Terence, Naomi, everyone!– to be wonderfully welcoming and warm. I am looking forward to learning more, and I hope you will share in my excitement.

If you have questions about Manifold, sign up for our newsletter, follow/star/love our git repository, follow @ManifoldScholar on Twitter, and feel free to get in touch.

Thanks and be well,


This Week in Manifold: Project Detail Improvements

Welcome to a new regular feature on the Building Manifold blog: “This Week in Manifold.” As we move toward a beta version of Manifold (scheduled for March, 2017), I’ll be releasing a Manifold build to our staging server every Friday afternoon. Each release will be accompanied by a blog post explaining what the development team accomplished in the sprint leading up to the release. This post comes a few days late. When the Internet broke last week, our ability to release builds from Github was impacted, which delayed things a bit. I expect we’ll be back on schedule this week, with our next build going out on Friday, October 28.

Nota Bene: Our staging instance of Manifold is currently on a private server. However, we’ll be opening it up to the public in a few weeks, as soon as we’re able to load an initial set of texts with open access rights onto the platform. Once that happens, it will be possible for readers of this blog to check out our weekly builds for themselves.

Our last development sprint focused on tightening up existing code, mainly around the project detail view. Notable changes included the following:


  • Refactored login overlay CSS for improved reusability
  • Refactored the authentication reducer
  • Significantly reorganized client frontend components for easier readability and reusability

Features and Improvements

  • Exposed “published” boolean attribute on Texts in the API
  • Stubbed markup and styles for the resource collection detail component
  • Stubbed markup and styles for the collection list component
  • Stubbed markup and styles for the resource list component
  • Improved client application exception handling
  • Upgraded React to 15.4.0-RC3
  • Implemented project importer that imports projects, texts, and resources from json manifest
  • Expanded project API to expose all data shown in the comps
  • Adjusted component to show project creator names below project thumbnails
  • Adjusted component to show actual project dates below project thumbnails
  • Stubbed markup and styles for project events (on project detail, and stand-alone), aka activity
  • Added mobile styles for event lists
  • Added metadata JSONB field type to projects and expose via API
  • Implemented actual project metadata in the project detail component

Tooling and Libraries

  • Switched Manifold client testing framework to Jest
  • Updated all client NPM modules
  • DRY’d up client application Webpack configuration
  • Reorganized and improved build and server scripts for client application
  • Improved API application Puma configuration
  • Switched client from NPM to Yarn for deterministic dependency resolution (and speed)
  • Removed redux-devtools component; replace with similar Chrome extension
  • Added moment module for handling dates and times
  • Updated global and API Rubies to version 2.3.1

Bug Fixes

  • Corrected login overlay view state
  • Removed randomness from stubbed resource components (breaks universal rendering)
  • Added code to prevent client application from requesting “page” entities on every route change

In addition to these changes, the Manifold team also touched base last week during our recurring (bi-monthly) meeting. The group discussed text and project metadata requirements, the overall project roadmap, the agenda for our in-person Portland meeting in mid-November, among other things. Joining that call for the first time was JoJo Karlin, a Doctoral student in English at the CUNY Graduate Center who is working with Matt Gold on this project. You’ll be hearing more from JoJo in the coming weeks as she works to share Manifold updates and progress via this blog.

This week’s development sprint will be focused on a few main goals. Naomi will be finishing up markup and UX for the resource collection slideshow. Zach will be focused on the initial modeling of project resources and project resource collections in the API, and wiring that data up to the client. He’ll also be improving the project importer—delivered in last week’s release—to pull in sample resources for our demonstration projects and texts.

All work and no play makes for dull developers, and so I will leave you with a screenshot of Manifold’s new error screen (only visible in development mode), inspired by the first computer Zach ever owned, the illustrious Commodore 64.



Starting Points with the Manifold Digital Projects Editor

As Jason indicated in this space earlier, Manifold is not simply an endeavor to create a better publishing platform; it is an answer to the challenge of rethinking and reframing the concept of scholarly publishing. In broad strokes, scholarly publishing is very much still a print-centric enterprise. Despite the vast libraries of electronic publications available, the systems, mindsets, and expectations of the greater university press culture—including those of authors and the academy—are engineered specifically for print.

In terms of production, while many presses have augmented their procedures over the past two decades, those alterations tend to simply mirror print methods instead of refashioning them to account for digital materials and platforms. For other presses, third-party service providers, or packagers, handle the creation of electronic editions in parallel with print or as an afterthought to it. That is to say, even when print isn’t to be the only medium of publication, it still receives primacy over all other editions. When a question of formatting comes up, it’s a question to be resolved for print first. When internal elements are being scrutinized, they are done through a lens that foremost anticipates a static physical object.

We’ve reached a moment, however, when we need to step back from print and see it in the proper context among the myriad means of expression scholars now have at their disposal. And it’s time to grapple with the fact that scholarly publishing involves more than books, more than journals, more than print. It’s not tied to paper; it’s not a function of the software it passes through. Instead, it’s the expression of content in the most meaningful and impactful ways possible. In that context, university presses must become adaptive and able to treat materials that aren’t always easily categorized or codified just as well as they do traditional vehicles like a journal or monograph.

That is no small thing. The print paradigm has been refined and honed for generations. It is deeply ingrained, predicating the workings of every department within a press. Reengineering it is not something that will happen overnight. Nor should it. But nor should we let the print mold stand as a boulder, cordoning off those modes of expression that weren’t possible a few years ago or those just over the horizon.

Exploring those opportunities is the commitment of the Manifold team. We bring together the perspectives of the university press, the scholar, and the technologist to hone in on new ways presses can present scholarship, realistically adapt existing procedures to account for a broad spectrum of publishing output, and technically deliver those varied means of expression to the readership in ways they are expecting as well as in ways they are not.

As the Manifold digital projects editor, I am working closely with the platform developers at Cast Iron Coding, our partners at the GC Digital Scholarship Lab, authors, and press staff across departments here at Minnesota to help craft, test, and document replicable processes that will allow presses to shift from a publishing plan with a very specific terminus to one that celebrates projects as a spectrum of scholarly publication. In the weeks and months ahead, I’ll be returning here to talk more about the implications of that and the challenges we’re working through as we move from platform wireframes into more robust test cases.

Stay tuned. The fun is just starting!

—Terence Smyre, Manifold Digital Projects Editor

Thoughts from Editors and Authors on What Makes a Good Manifold Project

As Manifold Scholarship progresses through its first rounds of wireframes, editors at the University of Minnesota Press are already discussing the platform with authors and considering book projects. Manifold will have an impact on the full span of a project, from the early stages of researching and collecting data for a book, to the drafting of a proposal, to peer review and press evaluation, and across the iterative stages of a manuscript’s organic development leading to the peer reviewed, published edition. Just as Manifold is designed to transform the nature of scholarly publishing, we are also asking scholars, from their earliest articulations, to think elastically about the ways in which Manifold can expand their project beyond the static, physical book.

As I’ve been asking editors and press authors to describe what makes a project suitable for publication on Manifold, I’ve found myself reflecting on the limitations the traditional print book can impose on scholars.

One could argue that the traditional print scholarly monograph isn’t an accurate record of a research project. The fixed form of the book, for example, doesn’t reflect the long duration of research, the months of ethnography, the full compliment of data collection and archival deep-dives. The monograph doesn’t record the full chorus of voices that help shape a project, such as the feedback of colleagues and peers. Research is already iterative, benefitting from community dialogue and from interfacing with an array of media. It’s just that the current way of disseminating that research doesn’t reflect those pre-publication engagements.

Up to now, when authors have wanted to share with readers materials that can’t fit into a print book such as audio and video files, teaching tools, or archival materials, they have often had to host them on a disconnected website. There’s often little travel between the website and the physical book, and these websites quickly fade away, disconnected by link rot or taken down from university servers when a scholar switches institutions. But these objects are never ancillary—they are part and parcel of the work itself. One potential Manifold author remarked to me that the traditional book doesn’t offer readers the chance to review the primary materials and say, “I disagree.” Manifold will allow authors to embed these objects within or alongside the text so that readers can chart their own course through all the elements that make up a scholarly book and research project.

This feature is especially important to Manifold author Mara Mills, assistant professor of media, culture and communication at New York University. Mills was initially attracted to Manifold because it provided an opportunity to develop an accessible multimedia publication:

My manuscript-in-progress,“Print Disability and New Reading Formats,” examines the century-long history of electronic reading by those excluded from the inkprint book. The research for this project has involved the digital transfer of hundreds of historical sound recordings: shellac Talking Book records; open reel tapes of early text-to-tone and text-to-speech reading machine output; demonstration cassettes of early time stretching technology for “speed listening”; recordings of audio-described films and graphic novels. My book, about multimodal reading and the multiplicity of “the book,” simply cannot exist in inkprint format alone.

Often, authors finish a book project that distills hours of audio interviews into a handful of block quotes, or a gallery of scanned images from which they draw fifteen or twenty to produce in black and white on the printed page. The traditional monograph doesn’t always account for the labor of discovery and archiving that is a part of research. When copyright and ethics allow, authors will be able to share these archives with readers through Manifold.

Stephanie Boluk and Patrick Lemieux are currently authoring their first book, tentatively titled “Metgaming: Videogames and the Practice of Play,” which studies a critical practice and form of game design philosophy in which playing games, making games, and thinking about games occur simultaneously. The Manifold edition of their book will include original, playable games designed by the authors, but they also see the Manifold project as archiving a genre of media which is often elusive:

Given the kinds of practice-based research both documented and performed in the volume, we’re very excited to begin “Metagaming” with the Manifold team. Manifold not only offers the possibility to hyperlink to sources outside the text, replace figures with HD video, and embed our original games directly within the text, but could also function as a repository or archive for unique and hard-to-find software discussed and used throughout the book. We also hope Manifold will help to make “Metagaming” more accessible for students by offering additional educational resources like a podcast we are in the process of planning in which we interview metagamers featured in the chapters and 20-min video summaries discussing the content of each chapter.

This willingness to think beyond the book is what acquisitions editors are looking for in Manifold projects. Press director and acquiring editor Doug Armato explains:

With Manifold, I’m looking for publishing projects that can’t be fully realized in the fixed, single-dimension of the page. This is not just a matter of adding multi-media or live links, but of seeing a scholarly work in its context of a longer research project, making its archive visible and accessible, and enabling the reader feedback and discussion that shape a book’s creation and reception. Not every scholarly author will want to work this way, but some do and I want Manifold to provide a publishing home for them—and one they don’t have to build themselves, as with the authoring tools already out there.

We are developing Manifold to not only expand what can be included within the book, but also to break down the temporal barriers that separate years of research from the book’s publication for authors who want to engage their readers at an early stage, share drafts of chapters in order to try out ideas, and receive feedback and dialogue as a form of open peer review. Danielle Kasprzak is Humanities Editor at the press and also acquires and oversees the press’s Forerunners: Ideas First program, which publishes thoughts-in-process as digital works and as affordable print publications. Forerunners aims to collapse the current publishing timeline to twelve weeks, so timing is often on her mind. Kasprzak is most excited about getting ideas out into the world more quickly than the traditional publication schedules of print books:

Part of the reason why authors are attracted to Forerunners is the speed at which texts are released. I’m pleased that scholars from diverse disciplines have seen publishing their ideas in a speculative, early way as beneficial to their thinking process.

Mara Mills is also excited by the pre-publication aspects we are building into Manifold. For Mills, this pre-publication aspect of Manifold will be “a way to curate my sound materials, write a few introductory provocations, and invite others to think with me about what it means to read.”

This notion of curation is critical to what I am looking for in a Manifold book project. Manifold will track a work as it is conceptualized, researched, written, and read, giving readers access to primary research documents and data, links to related archives, rich media, social media, and reading tools. Taking advantage of these tools, an author will also become a curator, shaping archives, providing context for readers, and illustrating the varied parts that make up her book and larger research project. It will ask authors to collaborate with the press on questions of copyright and ethics, peer review and evaluation, and to consider how best to connect with readers (both within the academy and general readers) in meaningful ways.

Manifold will recode the very definition of the scholarly monograph. To realize that goal, we are looking for authors whose vision for their scholarly projects extends beyond the limitations of the traditional book.

— Jason Weidemann, Editorial Director

A Technical Introduction to Manifold

Hello Manifoldians!

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.

Server-side architecture

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 is built in Ruby and Rails. Specifically, we’re using what is currently edge Rails, and what will soon be Rails 5. The development team thought long and hard about what server-side language to use, which was mainly a debate about the relative merits of using Ruby or Javascript on the server. While we have many years of experience working with PHP, and understand that it is still a popular, easy choice among academic developers, we felt strongly that the advantages of Ruby—strong OOP support, support for more functional styles, cleaner and more consistent syntax, and the maturity of Rails—outweighed the disadvantages of a more complex execution model and smaller (but by no means small) developer community. Laravel, the current leading PHP framework, for all its notable strengths, lacks the completeness and maturity of Rails and Active Record. Our choice to go with edge rails, rather than stable Rails 4.x, was driven by the fact that our server-side component is only serving an API, and Rails 5 will eventually ship with an api-only flag. This means that many aspects of Rails—the view layer, sprockets, etc—have been removed, making for a more lightweight framework overall. Another strong reason for choosing Rails was the presence of a strong HTML/XML parsing library in Nokogiri. Manifold deals heavily (but not exclusively) in EPUBs, which are HTML documents. To pull those documents apart and recreate them in the browser, we need a powerful parsing tool, which we’ve found in Nokogiri.

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.

Client-side architecture

If we made a safe, conservative choice in Rails on the server-side, we’ve taken more of a leap on the client-side. The Manifold client is a single page application (SPA) that is built on React and Redux. Both are relatively new Javascript libraries (or frameworks, depending on how you look at things) that are rapidly gaining mindshare and popularity among front-end developers. For those who are unfamiliar, React is a Javascript library that simplifies the process of creating reusable components. Unlike other popular libraries such as Angular or Knockout, React does not attempt to solve the problem of two-way data binding. Instead, it is meant to be used with a specific architecture called Flux, which is structured around one-way data flow and immutability. Both React and Redux have a relatively small surface area. Redux APIs are small, and the library as a whole is under 15k.

At Cast Iron, we’ve worked with many Javascript frameworks, in particular Angular and Backbone. Over time, client-side development has become quite complex, and it’s our feeling that while Angular can work well on some projects, it doesn’t do enough to reduce that complexity. By restricting the way in which data can flow through the application, and abstracting away the asynchronicity that can make client-side development challenging, we’ve found Redux and React to be a powerful combination that allows us to iterate quickly without sacrificing quality or maintainability.

There are some challenges that come with developing a single page javascript application. For our purposes, the biggest challenge is to ensure that there is content loaded on the page before the javascript executes. We feel strongly that Manifold needs to be accessible to users with disability, to search engine crawlers, to screen readers, etc, and that we can’t count on a javascript environment. For this reason, the Manifold client will be served by a small Node/Express application running on the server. Most of the javascript that executes in the browser is built to be isomorphic (now also known as universal), which means that care has been taken to ensure that it can be executed in a server-side context (node) and in a client-side context (the browser). The practical outcome of this approach is that the server-side component will be able to fully render the HTML before sending the page to the client, which solves the many accessibility and SEO problems.

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.

At the language level, we’re relying heavily on ES6 and upcoming ES7 features. We’re using Babel to transpile ES6+ code down to ES5  so that it will run in IE9+, Firefox, and Safari. By using edge Javascript language features, our hope is that to some degree we will future proof Manifold code. For now, we’re limiting ourselves to ES6+ features that are at stage 1 or greater, and acknowledge that there is some risk even with stage 1.

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.

In Closing

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.

Opening Access: The Reinvention of the Academic Book

On Tuesday, November 10, I was very happy to participate in an online conversation convened by the Association of American University Presses (AAUP) on the topic of “Opening Access: The Reinvention of the Academic Book.” During the session, which was moderated by Jennifer Howard of the Chronicle of Higher Education, I discussed the Manifold Scholarship project and issues related to digital monographs with my fellow panelists Frances Pinter (Manchester University Press/Knowledge Unlatched), Peter Suber (Harvard University Berkman Center for Internet & Society), and Augusta Rohrbach (author of Thinking Outside the Book). An archived video of the session is below, along with descriptive information about the event. I’m grateful to the AAUP for this opportunity to discuss the project!

From AAUP:

Streamed live on Nov 10, 2015
How to publish the best possible scholarship in the best possible way is at the heart of AAUP members’ consideration of the value of university presses and the future of the academic book. There are two parallel streams of technological and cultural change that drive these debates: the model for access to scholarship (we might think of this as “who pays?”) and the format or process for “publishing” scholarship (particularly in the long-form focused fields of the humanities and social sciences.) As University Press Week is celebrated, and as part of the Academic Book Week Great Debate series, AAUP is sponsoring an online discussion between thinkers and practitioners swimming in both streams.

Moderated by Jennifer Howard (Chronicle of Higher Education), the conversation will include Frances Pinter (Manchester University Press/Knowledge Unlatched), a publisher of both traditional print and innovative Open Access monographs; Peter Suber (Harvard University Berkman Center for Internet & Society), one of the foremost theorists of Open Access; Augusta Rohrbach (author of Thinking Outside the Book), a scholar of book culture embedded in a world of digital communications; and Matthew K. Gold (CUNY Graduate Center), who, with the team on the Manifold project, is transforming scholarly publications into living digital works.

— Matthew K. Gold

Building Manifold

Welcome to Building Manifold, a blog that will document the process of creating Manifold Scholarship, a project at the University of Minnesota Press in partnership with the GC Digital Scholarship Lab at the Graduate Center, CUNY and Cast Iron Coding. Manifold Scholarship is funded through a generous grant from the Andrew W. Mellon Foundation as part of a series of 2015 grants made to university presses.

Manifold Scholarship is composed of two parts:

1) The creation of Manifold, an intuitive, collaborative, open-source platform for scholarly works. With iterative texts, powerful annotation tools, rich media support, and robust community dialogue, Manifold will transform scholarly publications into living digital works.

2) Rethinking the print-focused mode of scholarly authorship and university press editorial procedures and production workflows to accommodate the differences in creating content for iterative, networked publication.

Creating Manifold

Over the past decade, university presses have made substantial progress toward the first phase of making scholarly books digital—converting monographs into pdf and epub editions. This has been enabled by the compatibility of current publishing practice and scholarly publishing economics with these fixed formats—formats that extend, but that do not transform, the nature of scholarly publishing. Digital humanities projects, on the other hand, are designed to be iterative in nature, with the potential for revision and expansion as knowledge of a subject evolves.

Integrating university press publication with emerging practices of digital humanities scholarship, Manifold Scholarship breaks from the prevalent format-based terms “print,” “ebook,” and “enhanced ebook,” defining scholarly work instead as either “iterative” or “static,” with the latter term encompassing both print editions and their replicated, fixed ebook editions. In doing so, publishing conceptions and practices are productively reoriented toward a hybrid-publishing model of Open Access iterative books while simultaneously producing traditional, static formats, meeting the needs of many markets and distribution channels.

Rethinking Authorship, Procedures, and Workflow

Web-based iterative publishing requires a new understanding of what constitutes an author’s manuscript, and new editorial procedures to standardize and streamline author and editor workflow in a way that makes it manageable and sustainable for the scholarly community.

In past editorial models, scholars created a manuscript for print, and sometimes created an accompanying project website for ancillary materials. We are asking authors to consider, from the very beginning of the research process, developing and sharing their project iteratively. Research materials, filmed images, field notes, ethnographic materials, sketches, maps, audio recordings, interviews, and other forms of research that are used to write the monograph will have a place on Manifold so that scholars can share their work as it is being researched and written.

One of the greatest strengths of the university press is creating efficient and replicable publishing procedures; as a part of Manifold Scholarship, we will work collaboratively with authors on pilot projects, establishing a set of procedures and best practices for preparing the materials for web-based publication, while refining the production workflow needed to publish Manifold projects while simultaneously producing static formats.

The Next Steps

We are excited about Manifold Scholarship and about sharing our progress and our thinking as the project develops. We’re building Manifold on Rails 5, with Node and React; come back next week for a post by Cast Iron Coding partner Zach Davis, as he discusses our technology stack choices. In early November, Minnesota Editorial Director Jason Weidemann will discuss what makes a scholarly project suitable for publication on Manifold, and then CUNY Graduate Fellow Jeff Binder will discuss annotation.

We hope you’ll join us, and we look forward to your feedback.

— Doug Armato and Matthew K. Gold, Co-PIs


UPDATE: The Manifold beta is now available!!