CSDUMMI/field-manual

The Offical User's Guide to OrbitDB

The OrbitDB Field Manual

An end-to-end tutorial, an in-depth look at OrbitDB's architecture, and even some philosophical musings about decentralization and the distributed industry. From the creators of OrbitDB.

What's in the book?

The book opens with an introduction that gives an overview of the promises and risks of the distributed space, and describes OrbitDB and its use cases at a high level.

The tutorial begins by guiding you through building a JavaScript application from scratch. You will work through: installation and database creation; managing and structuring your data; networking, communicating, and sharing data in a peer-to-peer fashion; and finally managing distributed identity and access to the databases. By the end of the tutorial, you should have everything you need.

Next, Thinking Peer to Peer is a collection of essays that approach peer-to-peer engineering from a more intellectual and philosophical perspective. It is light on code and heavy on ideas. It is also open for community members to contribute essays of their own, pending editorial review.

Then, The Architecture of OrbitDB covers in-depth, in a more reference style, the structured and architecture of OrbitDB. It includes a description of ipfs-log, the core of OrbitDB, the data stores and finally how the orbit-db library brings it all together into a single, cohesive package that works both in the browser and on the command line.

What comes next? provides some guidance and suggestions about subsequent topics you should explore. This section serves as a launch pad to further your understanding of how our distributed future will be built.

And after all that, we have a chapter on how you might write custom Stores in OrbitDB in Customizing OrbitDB, written in the form of a second Tutorial, that is based on our first chapter.

How to read this book

While this book is best consumed by reading cover-to-cover, we understand that your time is valuable and you want to get the most out of it in the shortest amount of time. Here are some suggestions to digest the information efficiently.

If you are a technical person and want to use OrbitDB to build distributed, peer-to-peer applications, start with Part 1: The tutorial, move to Part 3: The Architecture of OrbitDB, and then read chapters from Part 2 and Part 4 as necessary to fill in any knowledge gaps you may have.

After reading Part 1, Part 3 and Part 2, you are equipped to read Part 5: Customizing OrbitDB.

If you do not want to write code, but instead want to understand peer-to-peer systems and architectures at a higher level, you should be able to get away with only reading Part 2: Thinking Peer to Peer, and then moving on to Part 4, followed by Part 3.

Please note that we may repeat ourselves in different parts of the book. This is intentional because we cannot guarantee people will read the sections of the book in order. Please skim any sections that you already feel like you understand.

Getting the book

Here you can download a copy of the book in the following free formats:

• PDF

Gaps and out-of-date sections

OrbitDB is an alpha phase software in an alpha industry. A risk of this fact is, that documentation can quickly become out-of-date and be filled with errors.

It is thus vital, that everyone reading the Field Manual from OrbitDB also stay in contact with the OrbitDB Community on Matrix or Gitter for questions and reporting of issues with the Manual.

Maintainers

Mark Henderson (@aphelionz) is the maintainer and lead author of the OrbitDB field manual. However, this work is built upon the efforts of many other people:

• @haadcode
• @shamb0t
• @vvp
• @RichardLitt
• @sirfumblestone

Contributing

This is a living, community-based document, which means it is for and can include you.

Anybody can:

1. give feedback on, or request modifications to, the tutorial;
2. submit an essay for inclusion in the "Thinking Peer to Peer" section.

To do so you are welcome to create a pull request.

Please look at and follow the Code of Conduct.

Building

Requires Pandoc to convert markdown to other formats.

1. Make your edits in the markdown files.
2. npm run lint to make sure your edits meet linting standards.
3. npm run build to populate the dist folder.
4. Manually audit the dist output to ensure no errors were made.
5. Create your PR!

License

The OrbitDB Field Manual is released under the Creative Commons Attribution-NonCommercial 4.0 International License by Haja Networks Oy.

Attribution-NonCommercial
CC BY-NC