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

If you are looking to use ssb-server to run a pub, consider using ssb-minimal-pub-server instead.

Join us in #scuttlebutt on freenode.

Install

How to Install

ssb-server

1. curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.34.0/install.sh | bash

2. npm install -g node-gyp

3. apt-get install autotools-dev automake

4. nvm install 10

5. nvm alias default 10

6. Then to add

   ssb-server

   to your available CLI commands, install it using the

   -g

   global flag:

   npm install -g ssb-server
   

7. nano ~/run-server.sh

   and input:

#!/bin/bash
while true; do
  ssb-server start
  sleep 3
done

Be sure to start the pub server from this script (as shown in step 10), as this script will run the pub server and restart it even if it crashes.

1. mkdir ~/.ssb/

2. nano ~/.ssb/config

   and input:

{
  "connections": {
    "incoming": {
      "net": [
        { "scope": "public", "host": "0.0.0.0", "external": "Your Host Name or Public IP", "transform": "shs", "port": 8008 }
      ]
    },
    "outgoing": {
      "net": [{ "transform": "shs" }]
    }
  }
}

1. Now run

   sh ~/run-server.sh

   in a detachable session (e.g. screens)

2. Detach the session and run

   ssb-server whoami

   to check to see if the server is working.

3. Now is the time to think of a really cool name for your new pub server. Once you have it run:

ssb-server publish --type about --about {pub-id (this is the output from ssb-server whoami)} --name {Your pubs awesome name}

1. Now it's time to create those invites! Just run

   ssb-server invite.create 1

   and send those codes to your friends.

Congratulations! You are now ready to scuttlebutt with your friends!

Note for those running

ssb-server

from a home computer. You will need to make sure that your router will allow connections to port 8008. Thus, you will need to forward port 8008 to the local IP address of the computer running the server (look up how to do this online). If you haven't done this step, when a client tries to connect to your server using the invite code, they will get an error that your invite code is not valid.

Applications

There are already several applications built on

ssb-server

• 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.

Starting an

ssb-server

Command Line Usage Example

Start the server with extra log detail Leave this running in its own terminal/window

bash
ssb-server start --logging.level=info

Javascript Usage Example

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

// add plugins
Server
  .use(require('ssb-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.

Calling

ssb-server

Functions

There are a variety of ways to call

ssb-server

Command Line Usage Example

The command

ssb-server

ssb-server

Now, in a separate terminal from the one where you ran

ssb-server start

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 ```

Javascript Usage Example

Note that the following involves using a separate JS package, called ssb-client. It is most suitable for connecting to a running

ssb-server

ssb-server

ssb-client

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

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

Because

ssb-server

ssb-server

Getting Started

• Install - Setup instructions
• Tutorial - Primer on developing with ssb-server
• API / CLI Reference (out of date, but still the best reference)
• ssb-config - a module which helps build config to start ssb-server with
• ssb-client - make a remote connection to the server
• Modules docs - see an overview of all the modules

Key Concepts

• Secure Scuttlebutt, ssb-server's global database protocol
• Content Hash Linking
• Secret Handshake, ssb-server's transport-layer security protocol
• Private Box, ssb-server's end-to-end security protocol
• Frequently Asked Questions

Further Reading

• Design Challenge: Avoid Centralization and Singletons
• Design Challenge: Sybil Attacks
• Using Trust in Open Networks

License

MIT