From b893ddc4826f57f1dd54aae95a3547d75034abc5 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 26 Nov 2018 10:44:16 -0500 Subject: [PATCH 1/8] docs(README.md): npm should not be capitalized --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 678b2e7..ea80239 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,7 @@ Read the **[GETTING STARTED](https://github.com/orbitdb/orbit-db/blob/master/GUI For the CLI tool to manage orbit-db database, see **[OrbitDB CLI](https://github.com/orbitdb/orbit-db-cli)**. -It can be installed from Npm with: +It can be installed from npm with: ``` npm install orbit-db-cli -g From ae79336d0ce7ddf67e5a73a15a4eb7683cd5ff73 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 26 Nov 2018 10:44:40 -0500 Subject: [PATCH 2/8] docs(FAQ.md): Touch FAQ and add introduction --- FAQ.md | 7 +++++++ 1 file changed, 7 insertions(+) create mode 100644 FAQ.md diff --git a/FAQ.md b/FAQ.md new file mode 100644 index 0000000..1a1986b --- /dev/null +++ b/FAQ.md @@ -0,0 +1,7 @@ +# Frequently Asked Questions + +OrbitDB, like all code, is in a state of constant development. Doubtless, you're going to have some questions. The purpose of this FAQ is to answer the most common questions regarding how to get OrbitDB up and running, how to address common issues, and how to deal with pitfalls and common errors implementing it. + +This is a living document. If you see an answer that could be improved, please [open an issue](https://github.com/orbitdb/orbit-db/issues/new) or submit a PR directly. If you think than a question is missing, please [open an issue](https://github.com/orbitdb/orbit-db/issues/new). If you think that there is a better way to resolve a question - perhaps by improving the `orbitdb --help` docs or by adding a feature - please [open an issue](https://github.com/orbitdb/orbit-db/issues/new). Sense a theme yet? :) + +This document is seeded by questions from people opening issues in this repository. If enough people ask the same question, we'll add one here and point newcomers to it. Please don't be offended if the maintainers say "read the FAQ" - it's our way of making sure we don't spend all of our time answering the same questions. From 723b6faf5d0ac9e70385adc885f2f2091277fb31 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 26 Nov 2018 10:45:13 -0500 Subject: [PATCH 3/8] docs(FAQ.md): Add #502 --- FAQ.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/FAQ.md b/FAQ.md index 1a1986b..72dc372 100644 --- a/FAQ.md +++ b/FAQ.md @@ -5,3 +5,7 @@ OrbitDB, like all code, is in a state of constant development. Doubtless, you're This is a living document. If you see an answer that could be improved, please [open an issue](https://github.com/orbitdb/orbit-db/issues/new) or submit a PR directly. If you think than a question is missing, please [open an issue](https://github.com/orbitdb/orbit-db/issues/new). If you think that there is a better way to resolve a question - perhaps by improving the `orbitdb --help` docs or by adding a feature - please [open an issue](https://github.com/orbitdb/orbit-db/issues/new). Sense a theme yet? :) This document is seeded by questions from people opening issues in this repository. If enough people ask the same question, we'll add one here and point newcomers to it. Please don't be offended if the maintainers say "read the FAQ" - it's our way of making sure we don't spend all of our time answering the same questions. + +## Can I recreate the entire database on another machine based on the address? + +A database can't be "recreated" without downloading the database from other peers. Knowing an address will allow a user to open the database, which automatically connects to other peers who have the database open, and downloads the database which then "recreates" the database state locally, ie. replicates the database. From 748aaca7d78d75fb82365d02e3ad4400ee8f5e34 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 26 Nov 2018 10:46:35 -0500 Subject: [PATCH 4/8] docs(FAQ.md): Add #503 There is still some work to do there, though. @tyleryasaka has a question in #503 which should be answered first. --- FAQ.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/FAQ.md b/FAQ.md index 72dc372..c7cd40b 100644 --- a/FAQ.md +++ b/FAQ.md @@ -9,3 +9,11 @@ This document is seeded by questions from people opening issues in this reposito ## Can I recreate the entire database on another machine based on the address? A database can't be "recreated" without downloading the database from other peers. Knowing an address will allow a user to open the database, which automatically connects to other peers who have the database open, and downloads the database which then "recreates" the database state locally, ie. replicates the database. + +## Is every 'put' to OrbitDB immediately sent to the network and persisted? + +When calling `put` or any other update operation on a database, the data is 1) saved locally and persisted to IPFS and 2) send to the network, through IPFS Pubsub, to peers who have the database open (ie. peers). + +Upon calling `put` (or other updates), OrbitDB saves the data locally and returns. That is, the operation and its data is saved to the local node only after which `put` returns and *asynchronously* sends a message to pubsub peers. OrbitDB doesn't have a notion of confirming replication status from other peers (although this can be added on user-level) and considers operation a success upon persisting it locally. OrbitDB doesn't use consensus nor does it wait for the network to confirm operations making it an *eventually consistent* system. + +In short: it can't be assumed that data has been replicated to the network after an update-operation call finishes (eg. `put`, `add`). \ No newline at end of file From c918a6078bf568b52c3792208acb74680f2842a0 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 26 Nov 2018 10:47:30 -0500 Subject: [PATCH 5/8] docs(FAQ.md): Add #504 --- FAQ.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/FAQ.md b/FAQ.md index c7cd40b..41d4dd2 100644 --- a/FAQ.md +++ b/FAQ.md @@ -16,4 +16,10 @@ When calling `put` or any other update operation on a database, the data is 1) s Upon calling `put` (or other updates), OrbitDB saves the data locally and returns. That is, the operation and its data is saved to the local node only after which `put` returns and *asynchronously* sends a message to pubsub peers. OrbitDB doesn't have a notion of confirming replication status from other peers (although this can be added on user-level) and considers operation a success upon persisting it locally. OrbitDB doesn't use consensus nor does it wait for the network to confirm operations making it an *eventually consistent* system. -In short: it can't be assumed that data has been replicated to the network after an update-operation call finishes (eg. `put`, `add`). \ No newline at end of file +In short: it can't be assumed that data has been replicated to the network after an update-operation call finishes (eg. `put`, `add`). + +## Does OrbitDB already support pinning when using js-ipfs ? + +Currently js-ipfs doesn't have GC, so nothing gets removed meaning everything is pinned by default. + +However, this will change in the future as js-ipfs gets GC and we want to make sure that OrbitDB is actually persisting everything (by default), so some work on pinning needs to happen. If you're using OrbitDB with go-ipfs (through js-ipfs-api), then GC happens and data may not be persisted anymore after a time. This is a known issue and we're planning to implement actual pinning (from IPFS perspective) soon. \ No newline at end of file From f323ceb7ba7790433701b667875167b55ce1de90 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 26 Nov 2018 10:48:11 -0500 Subject: [PATCH 6/8] docs(FAQ.md): Add #508 --- FAQ.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/FAQ.md b/FAQ.md index 41d4dd2..0666b2d 100644 --- a/FAQ.md +++ b/FAQ.md @@ -22,4 +22,10 @@ In short: it can't be assumed that data has been replicated to the network after Currently js-ipfs doesn't have GC, so nothing gets removed meaning everything is pinned by default. -However, this will change in the future as js-ipfs gets GC and we want to make sure that OrbitDB is actually persisting everything (by default), so some work on pinning needs to happen. If you're using OrbitDB with go-ipfs (through js-ipfs-api), then GC happens and data may not be persisted anymore after a time. This is a known issue and we're planning to implement actual pinning (from IPFS perspective) soon. \ No newline at end of file +However, this will change in the future as js-ipfs gets GC and we want to make sure that OrbitDB is actually persisting everything (by default), so some work on pinning needs to happen. If you're using OrbitDB with go-ipfs (through js-ipfs-api), then GC happens and data may not be persisted anymore after a time. This is a known issue and we're planning to implement actual pinning (from IPFS perspective) soon. + +## Does orbit have a shared feed between peers where multiple peers can append to the same feed? + +> "...or, is it done more like scuttlebutt, where each peer has their own feed" + +All databases (feeds) are shared between peers, so nobody "owns them" like users do in ssb (afaik). Multiple peers can append to the same db. @tyleryasaka is right in that each peer has their own copy of the db (the log) and they may have different versions between them but, as @tyleryasaka (correctly) describes, through the syncing/replication process the peers exchange "their knowledge of the db" (heads) with each other, the dbs/logs get merged. This is what the "CRDT" in ipfs-log enables. But from address/authority/ownership perspective, they all share the same feed. \ No newline at end of file From 19b288bb6c02dccdbafda94a6a7b11c6b1c127bd Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 26 Nov 2018 10:49:33 -0500 Subject: [PATCH 7/8] docs(FAQ.md): Add #505 --- FAQ.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/FAQ.md b/FAQ.md index 0666b2d..177069b 100644 --- a/FAQ.md +++ b/FAQ.md @@ -6,6 +6,10 @@ This is a living document. If you see an answer that could be improved, please [ This document is seeded by questions from people opening issues in this repository. If enough people ask the same question, we'll add one here and point newcomers to it. Please don't be offended if the maintainers say "read the FAQ" - it's our way of making sure we don't spend all of our time answering the same questions. +## Database replication is not working. Why? + +_The answer to this question is a work in progress. See [orbit-db#505](https://github.com/orbitdb/orbit-db/issues/505)._ + ## Can I recreate the entire database on another machine based on the address? A database can't be "recreated" without downloading the database from other peers. Knowing an address will allow a user to open the database, which automatically connects to other peers who have the database open, and downloads the database which then "recreates" the database state locally, ie. replicates the database. From ed79fdad554040e6cf8f673471b23dcc2026c633 Mon Sep 17 00:00:00 2001 From: Richard Littauer Date: Mon, 26 Nov 2018 10:55:28 -0500 Subject: [PATCH 8/8] docs: Add a Table of Contents and a Contribute section --- FAQ.md | 33 ++++++++++++++++++++++++++------- package.json | 2 +- 2 files changed, 27 insertions(+), 8 deletions(-) diff --git a/FAQ.md b/FAQ.md index 177069b..b6996d3 100644 --- a/FAQ.md +++ b/FAQ.md @@ -6,15 +6,30 @@ This is a living document. If you see an answer that could be improved, please [ This document is seeded by questions from people opening issues in this repository. If enough people ask the same question, we'll add one here and point newcomers to it. Please don't be offended if the maintainers say "read the FAQ" - it's our way of making sure we don't spend all of our time answering the same questions. -## Database replication is not working. Why? +**Questions** + + + +- [Database replication is not working. Why?](#database-replication-is-not-working-why) +- [Can I recreate the entire database on another machine based on the address?](#can-i-recreate-the-entire-database-on-another-machine-based-on-the-address) +- [Is every `put` to OrbitDB immediately sent to the network and persisted?](#is-every-put-to-orbitdb-immediately-sent-to-the-network-and-persisted) +- [Does OrbitDB already support pinning when using js-ipfs ?](#does-orbitdb-already-support-pinning-when-using-js-ipfs-) +- [Does orbit have a shared feed between peers where multiple peers can append to the same feed?](#does-orbit-have-a-shared-feed-between-peers-where-multiple-peers-can-append-to-the-same-feed) +- [Contribute](#contribute) + + + +--- + +### Database replication is not working. Why? _The answer to this question is a work in progress. See [orbit-db#505](https://github.com/orbitdb/orbit-db/issues/505)._ -## Can I recreate the entire database on another machine based on the address? +### Can I recreate the entire database on another machine based on the address? A database can't be "recreated" without downloading the database from other peers. Knowing an address will allow a user to open the database, which automatically connects to other peers who have the database open, and downloads the database which then "recreates" the database state locally, ie. replicates the database. -## Is every 'put' to OrbitDB immediately sent to the network and persisted? +### Is every `put` to OrbitDB immediately sent to the network and persisted? When calling `put` or any other update operation on a database, the data is 1) saved locally and persisted to IPFS and 2) send to the network, through IPFS Pubsub, to peers who have the database open (ie. peers). @@ -22,14 +37,18 @@ Upon calling `put` (or other updates), OrbitDB saves the data locally and return In short: it can't be assumed that data has been replicated to the network after an update-operation call finishes (eg. `put`, `add`). -## Does OrbitDB already support pinning when using js-ipfs ? +### Does OrbitDB already support pinning when using js-ipfs ? -Currently js-ipfs doesn't have GC, so nothing gets removed meaning everything is pinned by default. +Currently [js-ipfs](https://github.com/ipfs/js-ipfs) doesn't have GC, so nothing gets removed meaning everything is pinned by default. However, this will change in the future as js-ipfs gets GC and we want to make sure that OrbitDB is actually persisting everything (by default), so some work on pinning needs to happen. If you're using OrbitDB with go-ipfs (through js-ipfs-api), then GC happens and data may not be persisted anymore after a time. This is a known issue and we're planning to implement actual pinning (from IPFS perspective) soon. -## Does orbit have a shared feed between peers where multiple peers can append to the same feed? +### Does orbit have a shared feed between peers where multiple peers can append to the same feed? > "...or, is it done more like scuttlebutt, where each peer has their own feed" -All databases (feeds) are shared between peers, so nobody "owns them" like users do in ssb (afaik). Multiple peers can append to the same db. @tyleryasaka is right in that each peer has their own copy of the db (the log) and they may have different versions between them but, as @tyleryasaka (correctly) describes, through the syncing/replication process the peers exchange "their knowledge of the db" (heads) with each other, the dbs/logs get merged. This is what the "CRDT" in ipfs-log enables. But from address/authority/ownership perspective, they all share the same feed. \ No newline at end of file +All databases (feeds) are shared between peers, so nobody "owns them" like users do in ssb (afaik). Multiple peers can append to the same db. @tyleryasaka is right in that each peer has their own copy of the db (the log) and they may have different versions between them but, as @tyleryasaka (correctly) describes, through the syncing/replication process the peers exchange "their knowledge of the db" (heads) with each other, the dbs/logs get merged. This is what the "CRDT" in ipfs-log enables. But from address/authority/ownership perspective, they all share the same feed. + +### How can I contribute to this FAQ? + +See the introduction at the top! Please open any issues and pull requests you can to improve this FAQ.md. It is here for you. If you're confused, ask another question publicly; it's possible that other people are, too. If you don't want to open an issue, feel free to jump onto [the Gitter](https://gitter.im/orbitdb/Lobby) and ask us there, too. \ No newline at end of file diff --git a/package.json b/package.json index 1953579..ceaeb0a 100644 --- a/package.json +++ b/package.json @@ -58,7 +58,7 @@ "build:examples": "webpack --config conf/webpack.example.config.js --sort-modules-by size && mkdir -p examples/browser/lib && cp node_modules/ipfs/dist/index.js examples/browser/lib/ipfs.js", "build:dist": "webpack --config conf/webpack.config.js --sort-modules-by size && mkdir -p examples/browser/lib && cp dist/orbitdb.min.js examples/browser/lib/orbitdb.min.js", "build:debug": "webpack --config conf/webpack.debug.config.js --sort-modules-by size && mkdir -p examples/browser/lib && cp dist/orbitdb.js examples/browser/lib/orbitdb.js && cp dist/orbitdb.js.map examples/browser/lib/orbitdb.js.map", - "build:docs/toc": "markdown-toc --no-first1 -i README.md && markdown-toc --no-first1 -i API.md && markdown-toc --no-first1 -i GUIDE.md && markdown-toc --no-first1 -i CHANGELOG.md", + "build:docs/toc": "markdown-toc --no-first1 -i README.md && markdown-toc --no-first1 -i API.md && markdown-toc --no-first1 -i GUIDE.md && markdown-toc --no-first1 -i CHANGELOG.md && markdown-toc --no-first1 -i FAQ.md ", "build:es5": "babel src --out-dir ./dist/es5/ --presets babel-preset-es2015 --plugins babel-plugin-transform-runtime" } }