git ssb

4+

Dominic / scuttlebot



Tree: 6e4655879fd3faa61b89d8dd00325d6ab82cf389

Files: 6e4655879fd3faa61b89d8dd00325d6ab82cf389 / index.html

13427 bytesRaw
1<html>
2    <head>
3    <title>Scuttlebot - SSBC</title>
4    <link rel="stylesheet" href="/normalize.css">
5    <link rel="stylesheet" href="/styles.css">
6    <link rel="stylesheet" href="/atelier-forest-light.css">
7    <script src="/highlight.pack.js"></script>
8    <script>hljs.initHighlightingOnLoad();</script>
9  </head>
10    <body>
11      <div id="topnav">
12    <div id="topnav-inner">
13      <a class="topnav-item " href="/" title="Home">
14      Home<br><small>SSBC</small>
15    </a>
16      <a class="topnav-item " href="/patchwork" title="Patchwork">
17      Patchwork<br><small>Social Messaging App</small>
18    </a>
19      <a class="topnav-item " href="https://handbook.scuttlebutt.nz/guides/ssb-server/install" title="Scuttlebot">
20      Scuttlebot<br><small>P2P Log Store</small>
21    </a>
22      <a class="topnav-item " href="/docs" title="Documentation">
23      Documentation<br><small>APIs, Articles</small>
24    </a>
25    </div>
26  </div>
27      <div id="layout">
28        <div id="leftnav">
29      <div class="leftnav-item selected">
30      <a href="/ssb-server" title="Scuttlebot">Scuttlebot</a>
31    </div>
32      <div class="leftnav-subitems">
33        <div class="leftnav-item ">
34      <a href="https://handbook.scuttlebutt.nz/guides/ssb-server/install" title="Install">Install</a>
35    </div>
36        <div class="leftnav-item ">
37      <a href="https://handbook.scuttlebutt.nz/guides/ssb-server/tutorial" title="Tutorial">Tutorial</a>
38    </div>
39        <div class="leftnav-item ">
40      <a href="https://github.com/ssbc/ssb-db/blob/master/api.md" title="API / CLI Reference">API / CLI Reference</a>
41    </div>
42      </div>
43      <div class="leftnav-item">Examples</div>
44      <div class="leftnav-subitems">
45        <div class="leftnav-item ">
46      <a href="/ssb-cli-dashboard" title="Blessed Dashboard">Blessed Dashboard</a>
47    </div>
48        <div class="leftnav-item ">
49      <a href="/ssb-simple-whois" title="Example "Whois"">Example "Whois"</a>
50    </div>
51        <div class="leftnav-item ">
52      <a href="/ssb-example-pm" title="Private Message">Private Message</a>
53    </div>
54      </div>
55      <div class="leftnav-item">Howto Guides</div>
56      <div class="leftnav-subitems">
57        <div class="leftnav-item ">
58      <a href="https://handbook.scuttlebutt.nz/guides/pubs/setup-a-pub" title="Setup a Pub">Setup a Pub</a>
59    </div>
60        <div class="leftnav-item ">
61      <a href="https://handbook.scuttlebutt.nz/guides/ssb-server/create-a-js-client" title="Create a JS Client">Create a JS Client</a>
62    </div>
63        <div class="leftnav-item ">
64      <a href="https://handbook.scuttlebutt.nz/guides/ssb-server/get-your-id" title="Get your ID">Get your ID</a>
65    </div>
66        <div class="leftnav-item ">
67      <a href="https://handbook.scuttlebutt.nz/guides/ssb-server/get-your-address" title="Get your Address">Get your Address</a>
68    </div>
69        <div class="leftnav-item ">
70      <a href="https://handbook.scuttlebutt.nz/guides/ssb-server/publish-a-post" title="Publish a Post">Publish a Post</a>
71    </div>
72        <div class="leftnav-item ">
73      <a href="https://handbook.scuttlebutt.nz/guides/ssb-server/publish-a-file" title="Publish a File">Publish a File</a>
74    </div>
75        <div class="leftnav-item ">
76      <a href="https://handbook.scuttlebutt.nz/guides/ssb-server/publish-encrypted-messages" title="Publish Encrypted Messages">Publish Encrypted Messages</a>
77    </div>
78        <div class="leftnav-item ">
79      <a href="https://handbook.scuttlebutt.nz/guides/ssb-server/follow-unfollow" title="Follow/Unfollow">Follow/Unfollow</a>
80    </div>
81        <div class="leftnav-item ">
82      <a href="https://handbook.scuttlebutt.nz/guides/pubs/announce-a-pub-server" title="Announce a Pub Server">Announce a Pub Server</a>
83    </div>
84        <div class="leftnav-item ">
85      <a href="https://handbook.scuttlebutt.nz/guides/pubs/create-an-invite" title="Create an Invite">Create an Invite</a>
86    </div>
87        <div class="leftnav-item ">
88      <a href="/docs/scuttlebot/howto-use-an-invite.html" title="Use an Invite">Use an Invite</a>
89    </div>
90        <div class="leftnav-item ">
91      <a href="https://handbook.scuttlebutt.nz/guides/ssb-server/update-your-profile" title="Update your Profile">Update your Profile</a>
92    </div>
93      </div>
94    </div>
95        <div id="content">
96          <h1 id="ssb-server">ssb-server</h1>
97<p>ssb-server is an open source <strong>peer-to-peer log store</strong> used as a database, identity provider, and messaging system.
98It has:</p>
99<ul>
100<li>Global replication</li>
101<li>File-synchronization</li>
102<li>End-to-end encryption</li>
103</ul>
104<p><code>ssb-server</code> behaves just like a <a href="http://milinda.pathirage.org/kappa-architecture.com/">Kappa Architecture DB</a>.
105In the background, it syncs with known peers.
106Peers do not have to be trusted, and can share logs and files on behalf of other peers, as each log is an unforgeable append-only message feed.
107This means ssb-servers comprise a <a href="https://en.wikipedia.org/wiki/Gossip_protocol">global gossip-protocol mesh</a> without any host dependencies.</p>
108<p>If you are looking to use ssb-server to run a pub, consider using <a href="https://github.com/ssbc/ssb-minimal-pub-server">ssb-minimal-pub-server</a> instead.</p>
109<p><strong>Join us in #scuttlebutt on freenode.</strong></p>
110<p><a href="http://travis-ci.org/ssbc/ssb-server"><img src="https://secure.travis-ci.org/ssbc/ssb-server.png" alt="build status"></a></p>
111<h2 id="install">Install</h2>
112<p>To add <code>ssb-server</code> to your available CLI commands, install it using the <code>-g</code> global flag:</p>
113<pre><code>npm install -g ssb-server
114</code></pre><h2 id="applications">Applications</h2>
115<p>There are already several applications built on <code>ssb-server</code>,
116one of the best ways to learn about secure-scuttlebutt is to poke around in these applications.</p>
117<ul>
118<li><a href="http://github.com/ssbc/patchwork">patchwork</a> is a discussion platform that we use to anything and everything concerning ssb and decentralization.</li>
119<li><a href="http://github.com/ssbc/patchbay">patchbay</a> is another take on patchwork - it&#39;s compatible, less polished, but more modular. The main goal of patchbay is to be very easy to add features to.</li>
120<li><a href="https://github.com/clehner/git-ssb">git-ssb</a> is git (&amp; github!) on top of secure-scuttlebutt. Although we still keep our repos on github, primary development is via git-ssb.</li>
121</ul>
122<p>It is recommended to get started with patchwork, and then look into git-ssb and patchbay.</p>
123<h2 id="starting-an-ssb-server">Starting an <code>ssb-server</code></h2>
124<h3 id="command-line-usage-example">Command Line Usage Example</h3>
125<p>Start the server with extra log detail
126Leave this running in its own terminal/window</p>
127<pre><code class="lang-bash">ssb-server start --logging.level=info
128</code></pre>
129<h3 id="javascript-usage-example">Javascript Usage Example</h3>
130<pre><code class="lang-js">var Server = require(&#39;ssb-server&#39;)
131var config = require(&#39;ssb-config&#39;)
132var fs = require(&#39;fs&#39;)
133var path = require(&#39;path&#39;)
134
135// add plugins
136Server
137  .use(require(&#39;ssb-master&#39;))
138  .use(require(&#39;ssb-gossip&#39;))
139  .use(require(&#39;ssb-replicate&#39;))
140  .use(require(&#39;ssb-backlinks&#39;))
141
142var server = Server(config)
143
144// save an updated list of methods this server has made public
145// in a location that ssb-client will know to check
146var manifest = server.getManifest()
147fs.writeFileSync(
148  path.join(config.path, &#39;manifest.json&#39;), // ~/.ssb/manifest.json
149  JSON.stringify(manifest)
150)
151</code></pre>
152<p>see: <a href="https://github.com/ssbc/ssb-config">github.com/ssbc/<strong>ssb-config</strong></a> for custom configuration.</p>
153<h2 id="calling-ssb-server-functions">Calling <code>ssb-server</code> Functions</h2>
154<p>There are a variety of ways to call <code>ssb-server</code> methods, from a command line as well as in a javascript program.</p>
155<h3 id="command-line-usage-example">Command Line Usage Example</h3>
156<p>The command <code>ssb-server</code> can also used to call the running <code>ssb-server</code>.</p>
157<p>Now, in a separate terminal from the one where you ran <code>ssb-server start</code>, you can run commands such as the following:</p>
158<pre><code class="lang-bash"># publish a message
159ssb-server publish --type post --text &quot;My First Post!&quot;
160
161# stream all messages in all feeds, ordered by publish time
162ssb-server feed
163
164# stream all messages in all feeds, ordered by receive time
165ssb-server log
166
167# stream all messages by one feed, ordered by sequence number
168ssb-server hist --id $FEED_ID
169</code></pre>
170<h3 id="javascript-usage-example">Javascript Usage Example</h3>
171<p>Note that the following involves using a separate JS package, called <a href="https://github.com/ssbc/ssb-client">ssb-client</a>. It is most suitable for connecting to a running <code>ssb-server</code> and calling its methods. To see further distinctions between <code>ssb-server</code> and <code>ssb-client</code>, check out this <a href="https://handbook.scuttlebutt.nz/guides/ssb-server-context">handbook article</a>.</p>
172<pre><code class="lang-js">var pull = require(&#39;pull-stream&#39;)
173var Client = require(&#39;ssb-client&#39;)
174
175// create a ssb-server client using default settings
176// (server at localhost:8080, using key found at ~/.ssb/secret, and manifest we wrote to `~/.ssb/manifest.json` above)
177Client(function (err, server) {
178  if (err) throw err
179
180  // publish a message
181  server.publish({ type: &#39;post&#39;, text: &#39;My First Post!&#39; }, function (err, msg) {
182    // msg.key           == hash(msg.value)
183    // msg.value.author  == your id
184    // msg.value.content == { type: &#39;post&#39;, text: &#39;My First Post!&#39; }
185    // ...
186  })
187
188  // stream all messages in all feeds, ordered by publish time
189  pull(
190    server.createFeedStream(),
191    pull.collect(function (err, msgs) {
192      // msgs[0].key == hash(msgs[0].value)
193      // msgs[0].value...
194    })
195  )
196
197  // stream all messages in all feeds, ordered by receive time
198  pull(
199    server.createLogStream(),
200    pull.collect(function (err, msgs) {
201      // msgs[0].key == hash(msgs[0].value)
202      // msgs[0].value...
203    })
204  )
205
206  // stream all messages by one feed, ordered by sequence number
207  pull(
208    server.createHistoryStream({ id: &lt; feedId &gt; }),
209    pull.collect(function (err, msgs) {
210      // msgs[0].key == hash(msgs[0].value)
211      // msgs[0].value...
212    })
213  )
214})
215</code></pre>
216<h2 id="use-cases">Use Cases</h2>
217<p><code>ssb-server</code>&#39;s message-based data structure makes it ideal for mail and forum applications (see <a href="https://ssbc.github.io/patchwork/">Patchwork</a>).
218However, it is sufficiently general to be used to build:</p>
219<ul>
220<li>Office tools (calendars, document-sharing, tasklists)</li>
221<li>Wikis</li>
222<li>Package managers</li>
223</ul>
224<p>Because <code>ssb-server</code> doesn&#39;t depend on hosts, its users can synchronize over WiFi or any other connective medium, making it great for <a href="https://en.wikipedia.org/wiki/Sneakernet">Sneakernets</a>.</p>
225<p><code>ssb-server</code> is <a href="https://en.wikipedia.org/wiki/Eventual_consistency">eventually-consistent with peers</a>, and requires exterior coordination to create strictly-ordered transactions.
226Therefore, by itself, it would probably make a poor choice for implementing a crypto-currency.
227(We get asked that a lot.)</p>
228<hr>
229<h3 id="getting-started">Getting Started</h3>
230<ul>
231<li><a href="https://handbook.scuttlebutt.nz/guides/ssb-server/install">Install</a> - Setup instructions</li>
232<li><a href="https://handbook.scuttlebutt.nz/guides/ssb-server/tutorial">Tutorial</a> - Primer on developing with ssb-server</li>
233<li><a href="https://scuttlebot.io/apis/scuttlebot/ssb.html">API / CLI Reference</a> (out of date, but still the best reference)</li>
234<li><a href="https://github.com/ssbc/ssb-config">ssb-config</a> - a module which helps build config to start ssb-server with</li>
235<li><a href="https://github.com/ssbc/ssb-client">ssb-client</a> - make a remote connection to the server</li>
236<li><a href="https://modules.scuttlebutt.nz">Modules docs</a> - see an overview of all the modules</li>
237</ul>
238<h3 id="key-concepts">Key Concepts</h3>
239<ul>
240<li><a href="https://ssbc.github.io/scuttlebutt-protocol-guide/">Secure Scuttlebutt</a>, ssb-server&#39;s global database protocol</li>
241<li><a href="https://ssbc.github.io/docs/ssb/linking.html">Content Hash Linking</a></li>
242<li><a href="https://ssbc.github.io/docs/ssb/secret-handshake.html">Secret Handshake</a>, ssb-server&#39;s transport-layer security protocol</li>
243<li><a href="https://ssbc.github.io/docs/ssb/end-to-end-encryption.html">Private Box</a>, ssb-server&#39;s end-to-end security protocol</li>
244<li><a href="https://ssbc.github.io/docs/ssb/faq.html">Frequently Asked Questions</a></li>
245</ul>
246<h3 id="further-reading">Further Reading</h3>
247<ul>
248<li><a href="https://ssbc.github.io/docs/articles/design-challenge-avoid-centralization-and-singletons.html">Design Challenge: Avoid Centralization and Singletons</a></li>
249<li><a href="https://ssbc.github.io/docs/articles/design-challenge-sybil-attack.html">Design Challenge: Sybil Attacks</a></li>
250<li><a href="https://ssbc.github.io/docs/articles/using-trust-in-open-networks.html">Using Trust in Open Networks</a></li>
251</ul>
252<h1 id="license">License</h1>
253<p>MIT</p>
254
255        </div>
256      </div>
257    </body>
258  </html>

Built with git-ssb-web