easily host your own Secure ScuttleButt (SSB) pub in a docker container
Clone or download
ahdinosaur fix install.sh script
- update apt before installing
- wrap passed bash arguments in double-quotes: https://stackoverflow.com/a/3816747
Latest commit daa3972 Sep 25, 2018

README.md

ssb-pub

easily host your own Secure ScuttleButt (SSB) pub in a docker container

if you feel like sharing your pub, please add it to the informal registry of pubs as request-only or with a re-usable invite (invite.create 1000)!

❤️

table of contents

one-click setup

  1. go to Install on DigitalOcean at butt.nz
  2. choose your server size and region

digital-butt-step-1.png

  1. log in to Digital Ocean, if not done already
  2. add ssh keys, if not done already
  3. start creating your pub server! 🙌

digital-butt-step-2.png

  1. wait for a few minutes ⌛️

digital-butt-step-3.png

  1. log in to your server using ssh
ssh root@your.ip.address.here
  1. test your pub server works
./sbot whoami
  1. create your first invite!
./sbot invite.create 1

digital-butt-step-4.png

  1. invite and host your friends on Scuttlebutt 🏡
  1. give your pub a name and description
./sbot publish --type about --about "@your.pubs.id.here" --name "Pubby McPubFace" --description "everyone should have a pub, this is mine"
  1. setup your pub's domain name

point a domain name (example.com) to your pub server's IP address (using a DNS A record)

edit ./create-sbot to change host definition to say host=example.com where example.com is your domain name.

nano ./create-sbot

then stop, remove, and re-create sbot:

docker stop sbot
docker rm sbot
./create-sbot

(credit to seven1m/do-install-button for the Digital Ocean installer)

manual setup

install docker

to run a pub you need to have a static public IP, ideally with a DNS record (i.e.<hostname.yourdomain.tld>)

on a fresh Debian 9 box, as root

apt update
apt upgrade -y
apt install -y apt-transport-https ca-certificates curl software-properties-common
wget https://download.docker.com/linux/debian/gpg -O docker-gpg
sudo apt-key add docker-gpg
echo "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable" | sudo tee -a /etc/apt/sources.list.d/docker.list
apt update
apt install -y docker-ce
systemctl start docker
systemctl enable docker

install ssb-pub image

(option a) pull image from docker hub

docker pull ahdinosaur/ssb-pub

(option b) build image from source

from GitHub:

git clone https://github.com/ahdinosaur/ssb-pub.git
cd ssb-pub
docker build -t ssb-pub .

create sbot container

step 1. create a directory on the docker host for persisting the pub's data

mkdir ~/ssb-pub-data
chown -R 1000:1000 ~/ssb-pub-data

if migrating from an old server, copy your old secret and gossip.json (maybe also blobs) now.

rsync -avz ~/ssb-pub-data/blobs/sha256/ $HOST:~/ssb-pub-data/blobs/sha256/

step 2. run the container

create a ./create-sbot script:

cat > ./create-sbot <<EOF
#!/bin/sh

ssb_host=<hostname.yourdomain.tld>
memory_limit=$(($(free -b --si | awk '/Mem\:/ { print $2 }') - 200*(10**6)))

docker run -d --name sbot \
   -v ~/ssb-pub-data/:/home/node/.ssb/ \
   -e ssb_host="\$ssb_host" \
   -p 8008:8008 \
   --restart unless-stopped \
   --memory "\$memory_limit" \
   ahdinosaur/ssb-pub
EOF

where

  • --memory sets an upper memory limit of your total memory minus 200 MB (for example: on a 1 GB server this could be simplified to --memory 800m)

then

# make the script executable
chmod +x ./create-sbot
# run the script
./create-sbot

step 3. create ./sbot script

we will now create a shell script in ./sbot to help us command our Scuttlebutt server running:

# create the script
cat > ./sbot <<EOF
#!/bin/sh

docker exec -it sbot sbot \$@
EOF

then

# make the script executable
chmod +x ./sbot
# test the script
./sbot whoami

setup auto-healer

the ssb-pub has a built-in health check: sbot whoami.

when sbot becomes unhealthy (it will!), we want to kill the container, so it will be automatically restarted by Docker.

for this situation, we will use somarat/healer:

docker pull ahdinosaur/healer
docker run -d --name healer \
  -v /var/run/docker.sock:/tmp/docker.sock \
  --restart unless-stopped \
  ahdinosaur/healer

ensure containers are always running

sometimes the sbot or healer containers will stop running (despite --restart unless-stopped!).

for this sitaution, we will setup two cron job scripts:

echo "docker start sbot" | tee /etc/cron.hourly/sbot && chmod +x /etc/cron.hourly/sbot
echo "docker start healer" | tee /etc/cron.hourly/healer && chmod +x /etc/cron.hourly/healer

because docker start <service> is idempotent, it will not change anything if the service is already running, but if the service is not running it will start it.

(optional) add ssb-viewer plugin

enter your sbot container with:

docker exec -it sbot bash

then run:

npm install -g git-ssb
mkdir -p ~/.ssb/node_modules
cd ~/.ssb/node_modules
git clone ssb://%MeCTQrz9uszf9EZoTnKCeFeIedhnKWuB3JHW2l1g9NA=.sha256 ssb-viewer
cd ssb-viewer
npm install
sbot plugins.enable ssb-viewer

edit your config to include

{
  "plugins": {
    "ssb-viewer": true
  },
  "viewer": {
    "host": "0.0.0.0"
  }
}

edit your ./create-sbot to include -p 8807:8807.

stop, remove, and re-create sbot:

docker stop sbot
docker rm sbot
./create-sbot

command and control

create invites

from your server:

./sbot invite.create 1

from your local machine, using ssh:

ssh -t root@server ./sbot invite.create 1

start, stop, restart containers

for sbot

  • docker stop sbot
  • docker start sbot
  • docker restart sbot

for healer

  • docker stop healer
  • docker start healer
  • docker restart healer

update ssb-pub image

docker pull ahdinosaur/ssb-pub
docker stop sbot
docker rm sbot
./create-sbot