Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/ahdinosaur/ssb-pub
easily host your own Secure ScuttleButt (SSB) pub in a docker container
https://github.com/ahdinosaur/ssb-pub
Last synced: about 2 months ago
JSON representation
easily host your own Secure ScuttleButt (SSB) pub in a docker container
- Host: GitHub
- URL: https://github.com/ahdinosaur/ssb-pub
- Owner: ahdinosaur
- License: agpl-3.0
- Created: 2017-11-15T09:44:01.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2022-01-10T23:22:14.000Z (almost 3 years ago)
- Last Synced: 2024-10-20T04:39:51.293Z (about 2 months ago)
- Language: Shell
- Homepage: http://butt.nz/
- Size: 178 KB
- Stars: 158
- Watchers: 10
- Forks: 25
- Open Issues: 18
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# ssb-pub
**UNMAINTAINED**, for a maintained alternative to `ssb-pub`, see [`go-ssb-room`](https://github.com/ssb-ngi-pointer/go-ssb-room).
easily host your own [Secure ScuttleButt (SSB)](https://www.scuttlebutt.nz) pub in a docker container
if you feel like sharing your pub, please add it to [the informal registry of pubs](https://github.com/ssbc/scuttlebot/wiki/Pub-Servers) as a private pub with your contact details so newbies may request an invite from you!
(if you are running a pub version less than 2.2.0, please [upgrade](#upgrading)! :tada: )
:heart:
## table of contents
- [~~one-click setup~~](#one-click-setup)
- [manual setup](#manual-setup)
- [install docker](#install-docker)
- [install `ssb-pub` image](#install-ssb-pub-image)
- [create `sbot` container](#create-sbot-container)
- [setup auto-healer](#setup-auto-healer)
- [ensure containers are always running](#ensure-containers-are-always-running)
- [(optional) add `ssb-viewer` plugin](#optional-add-ssb-viewer)
- [kubernetes setup](#kubernetes-setup)
- [command and control](#command-and-control)
- [create invites](#create-invites)
- [stop, start, restart containers](#stop-start-restart-containers)
- [upgrading](#upgrading)
- [update `ssb-pub` image](#update-ssb-pub-image)
- [migrating from v1 to v2](#migrating-from-v1-to-v2)
## ~~one-click setup~~
(currently broken, soz)
1) go to [](http://butt.nz) at [http://legacy-installer.butt.nz/](http://legacy-installer.butt.nz/)
2) choose your server size and region
> 
3) log in to Digital Ocean, if not done already
4) add ssh keys, if not done already
5) start creating your pub server! :raised_hands:
> 
6) wait for a few minutes :hourglass:
> 
7) log in to your server using `ssh`
```shell
ssh [email protected]
```
8) test your pub server works
```shell
./sbot whoami
```
9) create your first invite!
```shell
./sbot invite.create 1
```
> 
10) invite and host your friends on [Scuttlebutt](https://www.scuttlebutt.nz) :house_with_garden:
> 11) 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"
> ```
>
> 12) 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 `~/ssb-pub-data/config` to change the `connections.incoming.net[].external` property from your server ip address to your domain name:
>
> ```json
> {
> "connections": {
> "incoming": {
> "net": [
> {
> "scope": "public",
> "host": "0.0.0.0",
> "external": "hostname.yourdomain.tld",
> "transform": "shs",
> "port": 8008
> }
> ]
> },
> "outgoing": {
> "net": [
> {
> "transform": "shs"
> }
> ]
> }
> }
> }
> ```
>
> then restart sbot:
>
> ```shell
> docker restart sbot
> ```
(credit to [seven1m/do-install-button](https://github.com/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.``)
on a fresh Debian 9 box, as root
```shell
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
```shell
docker pull ahdinosaur/ssb-pub
```
#### (option b) build image from source
from GitHub:
```shell
git clone https://github.com/ahdinosaur/ssb-pub.git
cd ssb-pub
docker build -t ahdinosaur/ssb-pub .
```
### create `sbot` container
#### step 1. create a directory on the docker host for persisting the pub's data
```shell
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. setup ssb config
```shell
EXTERNAL=
cat > ~/ssb-pub-data/config < ./create-sbot < ./sbot <` is [idempotent](https://en.wikipedia.org/wiki/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:
```shell
docker exec -it sbot bash
```
then run:
```shell
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
```json
{
"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:
```shell
docker stop sbot
docker rm sbot
./create-sbot
```
## kubernetes setup
Yaml config files for Kubernetes are included in this repository at
`hack/k8s/deployment.yaml`. This has been tested on DigitalOcean. Tweaks may be
necessary for clusters hosted by other providers.
The SSB config file is injected into the container as a volume mount. You should
update the `ssb-config` configMap in the deployment file with your external IP
or domain, and any other changes you require. Unfortunately, because this is
being done on a subPath, changes to the configMap will not propogate
automatically. Please keep this in mind if you find you need to make config
changes, or, pull requests welcome.
SSB requires persistence to store the log, secrets. The chosen default in the
included config is 5gb, but you should raise this to a level that makes sense
for your traffic. If you should find your volume filling up, follow the
instructions for your provider as to how to increase the size or migrate to a
larger volume.
After updating the config, you can install SSB into your cluster with the
following:
```shell
kubectl apply -f hack/k8s/deployment.yaml
```
This will do a number of things:
1. create a namespace on your cluster called `scuttlebutt`
1. create a service exposing port 8008
1. create a 5gb persistent volume which is mapped to `/home/node/.ssb`
1. create and inject your ssb config
Much remains the same as with the manual install. However, since we're using
Kubernetes in this case for orchestration, there is no need to run additional
services like healer, etc. as liveness checks are handled by the deployment
configuration.
I've opted short-term _not_ to expose ssh access to the running container, but
you may access it by first getting the name of your running pod, then:
```shell
kubectl exec -it -n scuttlebutt /bin/bash
```
From here you can invoke any of the commands detailed below.
## command and control
### create invites
from your server:
```shell
./sbot invite.create 1
```
from your local machine, using ssh:
```shell
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`
## upgrading
### update `ssb-pub` image
```shell
docker pull ahdinosaur/ssb-pub
docker stop sbot
docker rm sbot
# edit ~/ssb-pub-data/config if necessary
./create-sbot
```
### migrating from `<2.2.0` to `2.2.0+`
edit your `~/ssb-pub-data/config`, such that **`connections.incoming.net[].external`** changes from an array of strings to a single string.
```diff
{
"connections": {
"incoming": {
"net": [
{
"scope": "public",
"host": "0.0.0.0",
- "external": ["hostname.yourdomain.tld"],
+ "external": "hostname.yourdomain.tld",
"transform": "shs",
"port": 8008
}
]
},
"outgoing": {
"net": [
{
"transform": "shs"
}
]
}
}
}
```
### migrating from `v1` to `v2`
for a `v1` pub owner to update to the latest `v2` version of `ssb-pub`:
1. pull the latest v2 image: `docker pull ahdinosaur/ssb-pub`
2. stop sbot container: `docker stop sbot`
3. remove sbot container: `docker rm sbot`
4. [create `~/ssb-pub-data/config`](#step-2-setup-ssb-config)
5. [re-create `./create-sbot`](#step-3-run-the-container)
6. `./create-sbot`
check things are working with `docker logs sbot` and `./sbot whoami` :tada: