From 6558b697bed871cf1a816a12e7c942a990d16acd Mon Sep 17 00:00:00 2001 From: phritz Date: Mon, 18 Sep 2017 11:08:11 -1000 Subject: [PATCH] prep docs/decent/ for demo release (#3716) Updated content per aa's proposal, added olap use case directory. --- doc/decent/about-noms.md | 48 -------------- doc/decent/about.md | 64 +++++++++++++++++++ doc/decent/architectures.md | 1 + doc/decent/{demo-app.md => demo-ipfs-chat.md} | 17 +++-- doc/decent/demo-p2p-chat.md | 1 + .../{how-to-use-noms.md => quickstart.md} | 1 - doc/decent/{whats-next.md => status.md} | 1 - doc/decent/vision.md | 28 -------- doc/olap/about.md | 4 ++ 9 files changed, 81 insertions(+), 84 deletions(-) delete mode 100644 doc/decent/about-noms.md create mode 100644 doc/decent/about.md create mode 100644 doc/decent/architectures.md rename doc/decent/{demo-app.md => demo-ipfs-chat.md} (75%) create mode 100644 doc/decent/demo-p2p-chat.md rename doc/decent/{how-to-use-noms.md => quickstart.md} (99%) rename doc/decent/{whats-next.md => status.md} (99%) delete mode 100644 doc/decent/vision.md create mode 100644 doc/olap/about.md diff --git a/doc/decent/about-noms.md b/doc/decent/about-noms.md deleted file mode 100644 index f1b97fa529..0000000000 --- a/doc/decent/about-noms.md +++ /dev/null @@ -1,48 +0,0 @@ -[About Noms](about-noms.md)  |  [How to Use Noms](how-to-use-noms.md)  |  [Demo App](demo-app.md)  |  [Vision](vision.md)  |  [What's Next](whats-next.md) -

-[![Build Status](http://jenkins3.noms.io/buildStatus/icon?job=NomsMasterBuilder)](http://jenkins3.noms.io/job/NomsMasterBuilder/) -[![codecov](https://codecov.io/gh/attic-labs/noms/branch/master/graph/badge.svg)](https://codecov.io/gh/attic-labs/noms) -[![GoDoc](https://godoc.org/github.com/attic-labs/noms?status.svg)](https://godoc.org/github.com/attic-labs/noms) -[![Slack](http://slack.noms.io/badge.svg)](http://slack.noms.io) - -# About Noms - -[Noms](http://noms.io) is a database for decentralized -applications. It stores structured data (ints, strings, blobs, maps, -lists, structs, etc) and like most databases it features atomic -transactions, efficient searches, scans, reads, and updates. - -Unlike any other database, Noms is built for the decentralized -web. Any number of dapp peers can concurrently modify their own copies -of the same Noms database and continuously sync their changes with -each other. In this sense noms works like git: changes are bundled as -commits which reference previous states of the database. Apps pull -changes from peers and merge them using a principled set of APIs and -strategies. Except that rather than users manually pulling and -merging, applications typically do this continuously, automatically -converging to a shared state. - -Noms stores data in the blockstore of your choice. For example you -could back Noms with a decentralized blockstore like IPFS. In this -configuration, read and write load is spread throughout the -network. If for some reason you wanted to sync to a centralized -service you could do that to (for example, S3). - -Your application uses a [Go client library](https://github.com/attic-labs/noms/blob/master/doc/go-tour.md) to interact with Noms -data. There is also a command-line interface for working with data and -initial support for a GraphQL-based query language. - -Some additional features include: -* **Versioning**: noms is git-like, so it’s easy to use, compare, or revert to older database versions -* **Efficient diffs**: diffing even huge datasets is efficient due to - noms’ use of a novel BTree-like data structure called a [Prolly - Tree](../intro.md#prolly-trees-probabilistic-b-trees) -* **Efficient storage**: data are chunked and content-addressable, so - there is exactly one copy of each chunk in the database, shared by - other data that reference it. Small changes to massive data - structures always result in small operations. -* **Verifiable**: The entire database rolls up to a single 20-byte hash - that uniquely represents the database at that moment - anyone can - verify that a particular database hashes to the same value - -Read the [Noms design overview](../intro.md). diff --git a/doc/decent/about.md b/doc/decent/about.md new file mode 100644 index 0000000000..10b756312f --- /dev/null +++ b/doc/decent/about.md @@ -0,0 +1,64 @@ +[About Noms](about-noms.md)  |  [How to Use Noms](how-to-use-noms.md)  |  [Demo App](demo-app.md)  |  [Vision](vision.md)  |  [What's Next](whats-next.md) +

+[![Build Status](http://jenkins3.noms.io/buildStatus/icon?job=NomsMasterBuilder)](http://jenkins3.noms.io/job/NomsMasterBuilder/) +[![codecov](https://codecov.io/gh/attic-labs/noms/branch/master/graph/badge.svg)](https://codecov.io/gh/attic-labs/noms) +[![GoDoc](https://godoc.org/github.com/attic-labs/noms?status.svg)](https://godoc.org/github.com/attic-labs/noms) +[![Slack](http://slack.noms.io/badge.svg)](http://slack.noms.io) + +# Noms -- The Decentralized Database + +[Noms](http://noms.io) makes it ~~easy~~ tractable to create rich, +multiuser, collaborative, fully-decentralized applications. + +Like most databases, Noms features a rich data model, atomic +transactions, support for large-scale data, and efficient searches, +scans, reads, and updates. + +Unlike any other database, Noms has built-in multiparty sync and +conflict resolution. Any number of dapp peers in a P2P network can +concurrently modify the same logical Noms database, and continuously +and efficiently sync their changes with each other. All peers will +converge to the same state. + +For many applications, peers can store an entire local copy of the +data they are interested in. For larger applications, it should be +possible to back Noms by a decentralized blockstore like IPFS, Swarm, +or Sia (or in the future, Filecoin), and store large-scale data in a +completely decentralized way, without replicating it on every +node. Noms also has a blockstore for S3, which is ideal for +applications that have some centralized components. + +## How it Works + +Think of Noms like a programmable Git: changes are bundled as commits +which reference previous states of the database. Apps pull changes +from peers and merge them using a principled set of APIs and +strategies. Except that rather than users manually pulling and +merging, applications typically do this continuously, automatically +converging to a shared state. + +Your application uses a [Go client +library](https://github.com/attic-labs/noms/blob/master/doc/go-tour.md) +to interact with Noms data. There is also a [command-line +interface](https://github.com/attic-labs/noms/blob/master/doc/cli-tour.md) +for working with data and initial support for a [GraphQL-based query +language](https://github.com/attic-labs/noms/blob/master/go/ngql/README.md). + +Some additional features include: +* **Versioning**: It’s easy to use, compare, or revert to older database versions +* **Efficient diffs**: diffing even huge datasets is efficient due to + noms’ use of a novel BTree-like data structure called a [Prolly + Tree](../intro.md#prolly-trees-probabilistic-b-trees) +* **Efficient storage**: data are chunked and content-addressable, so + there is exactly one copy of each chunk in the database, shared by + other data that reference it. Small changes to massive data + structures always result in small operations. +* **Verifiable**: The entire database rolls up to a single 20-byte hash + that uniquely represents the database at that moment - anyone can + verify that a particular database hashes to the same value + +Read the [Noms design overview](../intro.md). + +*If you’d like to use noms in your project we’d love to hear from you*: +drop us an email ([noms@attic.io](mailto:noms@attic.io)) or send us a +message in slack ([slack.noms.io](http://slack.noms.io)). diff --git a/doc/decent/architectures.md b/doc/decent/architectures.md new file mode 100644 index 0000000000..8b13789179 --- /dev/null +++ b/doc/decent/architectures.md @@ -0,0 +1 @@ + diff --git a/doc/decent/demo-app.md b/doc/decent/demo-ipfs-chat.md similarity index 75% rename from doc/decent/demo-app.md rename to doc/decent/demo-ipfs-chat.md index cdd4dd3151..9474c7fc09 100644 --- a/doc/decent/demo-app.md +++ b/doc/decent/demo-ipfs-chat.md @@ -5,11 +5,11 @@ [![GoDoc](https://godoc.org/github.com/attic-labs/noms?status.svg)](https://godoc.org/github.com/attic-labs/noms) [![Slack](http://slack.noms.io/badge.svg)](http://slack.noms.io) +# Demo App: IPFS-based Decentralized Chat - -# Sample App: IPFS-based Decentralized Chat - -Demo app code is in the [ipfs-chat](https://github.com/attic-labs/noms/tree/master/samples/go/ipfs-chat/) directory. To get it up and running take the following steps: +Demo app code is in the +[ipfs-chat](https://github.com/attic-labs/noms/tree/master/samples/go/ipfs-chat/) +directory. To get it up and running take the following steps: * Use git to clone the noms repository onto your computer: ``` git clone git@github.com:attic-labs/noms.git or git clone https://github.com/attic-labs/noms.git @@ -27,9 +27,14 @@ go build ./ipfs-chat client --username --node-idx=2 ipfs:/tmp/ifps2::chat ``` -If desired, ipfs-chat can be run as a daemon which will replicate all chat content in a local store which will enable clients to go offline without causing data to become unavailable to other clients: +If desired, ipfs-chat can be run as a daemon which will replicate all +chat content in a local store which will enable clients to go offline +without causing data to become unavailable to other clients: + ``` ./ipfs-chat daemon --node-idx=3 ipfs:/tmp/ifps3::chat ``` -Note: the 'node-idx' argument ensures that each IPFS-based program uses a distinct set of ports. This is useful when running multiple IPFS-based programs on the same machine. +Note: the 'node-idx' argument ensures that each IPFS-based program +uses a distinct set of ports. This is useful when running multiple +IPFS-based programs on the same machine. diff --git a/doc/decent/demo-p2p-chat.md b/doc/decent/demo-p2p-chat.md new file mode 100644 index 0000000000..8b13789179 --- /dev/null +++ b/doc/decent/demo-p2p-chat.md @@ -0,0 +1 @@ + diff --git a/doc/decent/how-to-use-noms.md b/doc/decent/quickstart.md similarity index 99% rename from doc/decent/how-to-use-noms.md rename to doc/decent/quickstart.md index 0f280ba6ad..43210c81c7 100644 --- a/doc/decent/how-to-use-noms.md +++ b/doc/decent/quickstart.md @@ -5,7 +5,6 @@ [![GoDoc](https://godoc.org/github.com/attic-labs/noms?status.svg)](https://godoc.org/github.com/attic-labs/noms) [![Slack](http://slack.noms.io/badge.svg)](http://slack.noms.io) - # How to Use Noms in a Decentralized App If you’d like to use noms in your project we’d love to hear from you: diff --git a/doc/decent/whats-next.md b/doc/decent/status.md similarity index 99% rename from doc/decent/whats-next.md rename to doc/decent/status.md index d6853a2c6e..00cf641639 100644 --- a/doc/decent/whats-next.md +++ b/doc/decent/status.md @@ -5,7 +5,6 @@ [![GoDoc](https://godoc.org/github.com/attic-labs/noms?status.svg)](https://godoc.org/github.com/attic-labs/noms) [![Slack](http://slack.noms.io/badge.svg)](http://slack.noms.io) - # What's next for Noms? Our primary goal (as of 9/2017) is to **find users to drive the future diff --git a/doc/decent/vision.md b/doc/decent/vision.md deleted file mode 100644 index e39a769091..0000000000 --- a/doc/decent/vision.md +++ /dev/null @@ -1,28 +0,0 @@ -[About Noms](about-noms.md)  |  [How to Use Noms](how-to-use-noms.md)  |  [Demo App](demo-app.md)  |  [Vision](vision.md)  |  [What's Next](whats-next.md) -

-[![Build Status](http://jenkins3.noms.io/buildStatus/icon?job=NomsMasterBuilder)](http://jenkins3.noms.io/job/NomsMasterBuilder/) -[![codecov](https://codecov.io/gh/attic-labs/noms/branch/master/graph/badge.svg)](https://codecov.io/gh/attic-labs/noms) -[![GoDoc](https://godoc.org/github.com/attic-labs/noms?status.svg)](https://godoc.org/github.com/attic-labs/noms) -[![Slack](http://slack.noms.io/badge.svg)](http://slack.noms.io) - - -# Vision - -*Noms enables developers to build rich decentralized applications.* - -Decentralization promises to be the next great evolution of the Web. But developers today struggle to create even simple decentralized applications because there are no databases that work well in a decentralized environment. - -Our vision is to provide a database native to the decentralized web that includes: - -1. Efficient and correct multiparty sync and conflict resolution -1. Search across the entire network, including data that isn’t local -1. Paging of data from the network “lazily” as needed -1. Enforcement of business logic -1. Load-spreading to minimize hotspots -1. Data persistence: data should not lost when a node disconnects or goes away - -This vision is achievable. Today Noms can do (1), (2), and (3). We -have ideas for how to solve (4). Bittorrent and IPFS are existence -proofs for (5). We do not yet have a solution for (6), though there -are several promising efforts underway that may in the future provide -some of the tools we need (e.g., Filecoin). diff --git a/doc/olap/about.md b/doc/olap/about.md new file mode 100644 index 0000000000..44626f650e --- /dev/null +++ b/doc/olap/about.md @@ -0,0 +1,4 @@ +# Noms -- the OLAP database-in-a-bucket + +[Noms](http://noms.io) ... {description of OLAP use case, +similar to what we have for [the decentralized use case](/docs/decent/about.md)}