DOCSEARCHbyAlgolia
Submit Docs

ssb-server

repository·main·Indexed 23 days ago

https://github.com/ssbc/ssb-server

A network protocol layer for secure-scuttlebutt that functions as an open-source peer-to-peer log store, database, identity provider, and messaging system. Version 16.0.1 utilizes a gossip protocol for global replication, file synchronization, and end-to-end encryption without central host dependencies. It provides a CLI for managing identities and invites, as well as a Node.js module for integration into Javascript applications.

Tokens
1.9K
Snippets
7
Records
12
Agent score
83%

What's inside ssb-server

  1. Install ssb-server

    main

    To install ssb-server and set up a working pub, follow these steps on a Linux-based system:

    1. Install system dependencies: sudo apt install curl autotools-dev automake
    2. Install NVM (Node Version Manager): curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.34.0/install.sh | bash
    3. Load NVM into your current shell:
      export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
    4. Install and set Node.js 10 as default: nvm install 10 nvm alias default 10
    5. Install node-gyp globally: npm install -g node-gyp
    6. Install ssb-server globally: npm install -g ssb-server Note: If running as root, use npm install -g ssb-server --unsafe-perm.

    Important for Home Users: You must forward port 8008 on your router to the local IP address of the computer running the server to allow client connections.

    npm install -g ssb-server

  2. Start the ssb-server process

    main

    You can start the server directly via the CLI. It is recommended to run the server within a loop script to ensure it restarts automatically if it crashes.

    Recommended Restart Script (~/run-server.sh):

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

    CLI Command to start with info logging:

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

  3. Configure ssb-server network settings

    main

    Create a configuration file at ~/.ssb/config to define how your server handles incoming and outgoing connections. A standard configuration for a public server looks like this:

    {
  "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" }]
    }
  }
}

    Ensure that transform is set to shs (Secret Handshake) and that your firewall/router allows traffic on the specified port (e.g., 8008).

    {
  "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" }]
    }
  }
}

  4. Use ssb-server command aliases

    main
    The CLI includes command aliases to simplify common operations. These aliases are applied to both the RPC interface and the manifest, allowing for more intuitive command usage in the terminal.

  5. Use ssb-client to call ssb-server methods

    main

    To connect to a running ssb-server from a client application, use the ssb-client package. This allows you to publish messages and create streams using pull-stream.

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

// create a ssb-server client using default settings
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)
    })
  )

  // 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)
    })
  )

  // 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)
    })
  )
})
    var pull = require('pull-stream')
var Client = require('ssb-client')

Client(function (err, server) {
  if (err) throw err

  server.publish({ type: 'post', text: 'My First Post!' }, function (err, msg) {
  })

  pull(
    server.createFeedStream(),
    pull.collect(function (err, msgs) {
    })
  )

  pull(
    server.createLogStream(),
    pull.collect(function (err, msgs) {
    })
  )

  pull(
    server.createHistoryStream({ id: < feedId > }),
    pull.collect(function (err, msgs) {
    })
  )
})

  6. Use ssb-server in Javascript

    main

    To run ssb-server within a Node.js application, require the module and pass a configuration object (typically generated via ssb-config). You can also use .use() to attach plugins like ssb-gossip or ssb-replicate.

    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
var manifest = server.getManifest()
fs.writeFileSync(
  path.join(config.path, 'manifest.json'),
  JSON.stringify(manifest)
)
    var Server = require('ssb-server')
var config = require('ssb-config')
var fs = require('fs')
var path = require('path')

Server
  .use(require('ssb-master'))
  .use(require('ssb-gossip'))
  .use(require('ssb-replicate'))
  .use(require('ssb-backlinks'))

var server = Server(config)

var manifest = server.getManifest()
fs.writeFileSync(
  path.join(config.path, 'manifest.json'),
  JSON.stringify(manifest)
)

  7. Initialize and manage a pub via CLI

    main

    Once the server is running, use the ssb-server CLI to manage your identity and invites:

    1. Check identity: Run ssb-server whoami to get your public key (pub-id).
    2. Set pub name/about: ssb-server publish --type about --about {pub-id} --name {Your Name}
    3. Create invites: ssb-server invite.create 1 (generates invite codes for friends).

  8. Interact with ssb-server via CLI

    main

    If the server is already running, you can use the ssb-server command in a separate terminal to interact with it:

    • Publish a message: ssb-server publish --type post --text "My First Post!"
    • Stream all messages (ordered by publish time): ssb-server feed
    • Stream all messages (ordered by receive time): ssb-server log
    • Stream history for a specific feed (ordered by sequence number): ssb-server hist --id $FEED_ID
    ssb-server publish --type post --text "My First Post!"

  9. Initialize an ssb-server instance with createSsbServer()

    main
    You can initialize a pre-configured ssb-server instance by calling the default export or createSsbServer(). This instance is built using secret-stack and includes the ssb-db plugin by default, configured with standard ssb-caps capabilities. This is the primary way to get a running server instance with the necessary database and capability layers pre-attached.

  10. Start the ssb-server

    main

    To start the server, use the start command. This initializes the server with a standard set of plugins (including ssb-gossip, ssb-replicate, ssb-blobs, and ssb-query) and generates a manifest.json file in the configuration directory. This manifest is required for clients to connect to the server.

    Note: The command server is deprecated and has been renamed to start.

    ssb-server start

  11. Add blobs via the CLI

    main

    The blobs.add command allows you to upload data to the server. You can either provide a filename as an argument or pipe data from stdin.

    Usage:

    • Add a file: blobs.add <filename>
    • Read from stdin: source | blobs.add

  12. Configure ssb-server via CLI arguments

    main

    You can pass configuration options to ssb-server by using a double dash -- separator. Arguments before -- are treated as commands for the CLI, while arguments after -- are passed as configuration to the server via ssb-config.

    Example: ssb-server start --port 8080 --host 127.0.0.1