Skip to content
The gossip and replication server for Secure Scuttlebutt - a distributed social network
Branch: master
Clone or download
Latest commit 6f24bf0 Mar 16, 2019
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github
lib
plugins refactor gossip out into ssb-gossip Jan 13, 2019
scripts pretest script should output which dep is conflicting, if so Feb 14, 2019
test
.gitignore
.travis.yml also travis node 10 May 8, 2018
README.md Update README example to reflect new refactoring (#639) Feb 21, 2019
api.md Rename as "ssb-server" Nov 13, 2018
bin.js Merge branch 'refactor' Jan 18, 2019
caps.js
index.js
npm-shrinkwrap.json 14.1.9 Mar 16, 2019
package.json 14.1.9 Mar 16, 2019

README.md

ssb-server

ssb-server is an open source peer-to-peer log store used as a database, identity provider, and messaging system. It has:

  • Global replication
  • File-synchronization
  • End-to-end encryption

ssb-server behaves just like a Kappa Architecture DB. In the background, it syncs with known peers. Peers 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. This means ssb-servers comprise a global gossip-protocol mesh without any host dependencies.

Join us in #scuttlebutt on freenode.

build status

install

a known-working shrinkwrapped version will be installed.

npm install -g ssb-server

Applications

There are already several applications built on ssb-server, one of the best ways to learn about secure-scuttlebutt is to poke around in these applications.

  • patchwork is a discussion platform that we use to anything and everything concerning ssb and decentralization.
  • patchbay is another take on patchwork - it's compatible, less polished, but more modular. The main goal of patchbay is to be very easy to add features to.
  • git-ssb is git (& github!) on top of secure-scuttlebutt. Although we still keep our repos on github, primary development is via git-ssb.

it is recommended to get started with patchwork, and then look into git-ssb and patchbay.

Example Usage (bash)

# Start the server with extra log detail
# Leave this running in its own terminal/window
ssb-server start --logging.level=info

# publish a message
ssb-server publish --type post --text "My First Post!"

# stream all messages in all feeds, ordered by publish time
ssb-server feed

# stream all messages in all feeds, ordered by receive time
ssb-server log

# stream all messages by one feed, ordered by sequence number
ssb-server hist --id $FEED_ID

Example Usage (js)

var Server = require('ssb-server')
var config = require('ssb-config')
var fs = require('fs')
var path = require('path')

// add plugins
Server
  .use(require('ssb-server/plugins/master'))
  .use(require('ssb-gossip'))
  .use(require('ssb-replicate'))
  .use(require('ssb-backlinks'))

var server = Server(config)

// save an updated list of methods this server has made public
// in a location that ssb-client will know to check
var manifest = server.getManifest()
fs.writeFileSync(
  path.join(config.path, 'manifest.json'), // ~/.ssb/manifest.json
  JSON.stringify(manifest)
)

see: github.com/ssbc/ssb-config for custom configuration.

elsewhere:

var pull = require('pull-stream')
var Client = require('ssb-client')

// create a ssb-server client using default settings
// (server at localhost:8080, using key found at ~/.ssb/secret, and manifest we wrote to `~/.ssb/manifest.json` above)
Client(function (err, server) {
  if (err) throw err

  // publish a message
  server.publish({ type: 'post', text: 'My First Post!' }, function (err, msg) {
    // msg.key           == hash(msg.value)
    // msg.value.author  == your id
    // msg.value.content == { type: 'post', text: 'My First Post!' }
    // ...
  })

  // stream all messages in all feeds, ordered by publish time
  pull(
    server.createFeedStream(),
    pull.collect(function (err, msgs) {
      // msgs[0].key == hash(msgs[0].value)
      // msgs[0].value...
    })
  )

  // stream all messages in all feeds, ordered by receive time
  pull(
    server.createLogStream(),
    pull.collect(function (err, msgs) {
      // msgs[0].key == hash(msgs[0].value)
      // msgs[0].value...
    })
  )

  // stream all messages by one feed, ordered by sequence number
  pull(
    server.createHistoryStream({ id: < feedId > }),
    pull.collect(function (err, msgs) {
      // msgs[0].key == hash(msgs[0].value)
      // msgs[0].value...
    })
  )
})

Use-cases

ssb-server's message-based data structure makes it ideal for mail and forum applications (see Patchwork). However, it is sufficiently general to be used to build:

  • Office tools (calendars, document-sharing, tasklists)
  • Wikis
  • Package managers

Because ssb-server doesn't depend on hosts, its users can synchronize over WiFi or any other connective medium, making it great for Sneakernets.

ssb-server is eventually-consistent with peers, and requires exterior coordination to create strictly-ordered transactions. Therefore, by itself, it would probably make a poor choice for implementing a crypto-currency. (We get asked that a lot.)


Getting Started

Key Concepts

Further Reading

License

MIT

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.