coop-cloud-chaos-patchs
/
go-ssb-room
0
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

update documentation, add screenshot

This commit is contained in:
cblgh 2021-04-26 14:38:00 +02:00
parent 1a1a25a792
commit 62668dbedd
3 changed files with 64 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
README.md
View File

@ -7,12 +7,18 @@ It includes:
* muxrpc handlers for tunneling connections
* a fully embedded HTTP server & HTML frontend, for administering the room
![](./docs/screenshot.png)
## Features
* [x] Rooms v1 (`tunnel.connect`, `tunnel.endpoints`, etc.)
* [x] Simple allow-listing, administerd via the web dashboard
* [x] Sign-in with SSB
* [ ] Alias management
* [x] User management (allow- & denylisting + moderator & administrator roles), all administered via the web dashboard
* [x] Multiple [privacy modes](https://ssb-ngi-pointer.github.io/rooms2/#privacy-modes)
* [x] [Sign-in with SSB](https://ssb-ngi-pointer.github.io/ssb-http-auth-spec/)
* [x] Alias management
## Getting started
For an architecture and instructions on setting up a webserver to use with `go-ssb-room`, [read the documentation](./docs).
## Development
@ -26,22 +32,29 @@ go build
./server -h
Usage of ./server:
-aliases-as-subdomains
needs to be disabled if a wildcard certificate for the room is not available. (default true)
-dbg string
listen addr for metrics and pprof HTTP server (default "localhost:6078")
-https-domain string
which domain to use for TLS and AllowedHosts checks
-lishttp string
address to listen on for HTTP requests (default ":3000")
-lismux string
address to listen on for secret-handshake+muxrpc (default ":8008")
-nounixsock
disable the UNIX socket RPC interface
-logs string
where to write debug output to (default is just stderr)
-mode value
the privacy mode (values: open, community, restricted) determining room access controls
-nounixsock
disable the UNIX socket RPC interface
-repo string
where to put the log and indexes (default "/home/cryptix/.ssb-go-room")
where to put the log and indexes (default "~/.ssb-go-room")
-shscap string
secret-handshake app-key (or capability) (default "1KHLiKZvAvjbY1ziZEHMXawbCEIM6qwjCDm3VYRan/s=")
-version
print version number and build date
```
If you want to view the development server in your browser:
@ -108,7 +121,7 @@ cd cmd/insert-user
go build
# optional step: run a script to generate a valid ssb id @<pubkey>.ed25519, useful for trying things out quickly
./generate-fake-id.sh
./insert-user -name <username> -key <@pubkey.ed25519>
./insert-user -login <username> -key <@pubkey.ed25519>
```
Then repeat your password twice and you are all set for development.
@ -132,6 +145,8 @@ The folder `web/handlers` contains the HTTP handlers for the dashboard. Each sub
## Authors
* [cryptix](https://github.com/cryptix) (`@p13zSAiOpguI9nsawkGijsnMfWmFd5rlUNpzekEE+vI=.ed25519`)
* [staltz](https://github.com/staltz)
* [cblgh](https://github.com/cblgh)
## License

51
docs/README.md
View File

@ -1,18 +1,40 @@
# Getting Started
There are two paths to starting your own room: creating a build from source, or downloading one
of the premade [releases](https://github.com/ssb-ngi-pointer/go-ssb-room/releases).
## Creating a build
* [Download Go](https://golang.org/doc/install) & [set up your Go environment](https://golang.org/doc/install#install). You will need at least Go v1.16.
* Download the repository `git clone git@github.com:ssb-ngi-pointer/go-ssb-room.git && cd go-ssb-room`
* [Read the development instructions](../README.md)
* You should now have a working go-ssb-room binary! Read the HTTP Hosting section below, for
more instructions on the last mile.
# Architecture
## Invite flow
This implementation of Rooms 2.0 is compliant with the [Rooms 2.0 specification](https://github.com/ssb-ngi-pointer/rooms2), but we add a few additional features and pages in order to improve user experience when their SSB app does not support [SSB URIs](https://github.com/ssb-ngi-pointer/ssb-uri-spec).
This implementation of Rooms 2.0 is compliant with the [Rooms 2.0
specification](https://github.com/ssb-ngi-pointer/rooms2), but we add a few additional features
and pages in order to improve user experience when their SSB app does not support [SSB
URIs](https://github.com/ssb-ngi-pointer/ssb-uri-spec).
A summary can be seen in the following chart:
![Chart](./invites-chart.png)
When the browser and operating system detects no support for opening SSB URIs, we redirect to a fallback page which presents the user with two broad options: (1) install an SSB app that supports SSB URIs, (2) link to another page where the user can manually input the user's SSB ID in a form.
When the browser and operating system detects no support for opening SSB URIs, we redirect to a
fallback page which presents the user with two broad options: (1) install an SSB app that
supports SSB URIs, (2) link to another page where the user can manually input the user's SSB ID
in a form.
## Sign-in flow
This implementation is compliant with [SSB HTTP Authentication](https://github.com/ssb-ngi-pointer/ssb-http-auth-spec), but we add a few additional features and pages in order to improve user experience. For instance, besides conventional SSB HTTP Auth, we also render a QR code to sign-in with a remote SSB app (an SSB identity not on the device that has the browser open). We also support sign-in with username/password, what we call "fallback authentication".
This implementation is compliant with [SSB HTTP
Authentication](https://github.com/ssb-ngi-pointer/ssb-http-auth-spec), but we add a few
additional features and pages in order to improve user experience. For instance, besides
conventional SSB HTTP Auth, we also render a QR code to sign-in with a remote SSB app (an SSB
identity not on the device that has the browser open). We also support sign-in with
username/password, what we call "fallback authentication".
A summary can be seen in the following chart:
@ -20,17 +42,28 @@ A summary can be seen in the following chart:
# HTTP Hosting
We currently assume a standard HTTPS server in front of go-ssb-room to facilitate TLS termination and certificate management. This should be possible with most modern HTTP servers since it's a pretty standard practice, known as [reverse proxying](https://en.wikipedia.org/wiki/Reverse_proxy).
We currently assume a standard HTTPS server in front of go-ssb-room to facilitate TLS
termination and certificate management. This should be possible with most modern HTTP servers
since it's a pretty standard practice, known as [reverse
proxying](https://en.wikipedia.org/wiki/Reverse_proxy).
Two bits of rationale:
1) People usually want to have more than one site on their server. Put differently, we could have [LetsEncrypt](https://letsencrypt.org/) inside the go-ssb-room server but it would have to listen on port :443—blocking the use of other domains on the same IP.
2) Listening on :443 can be pretty annoying (you might need root privileges or similar capabilities).
1) People usually want to have more than one site on their server. Put differently, we could
have [LetsEncrypt](https://letsencrypt.org/) inside the go-ssb-room server but it would have to
listen on port :443—blocking the use of other domains on the same IP. 2) Listening on :443 can
be pretty annoying (you might need root privileges or similar capabilities).
go-ssb-room needs three headers to function properly, which need to be forwarded by the webserver.
go-ssb-room needs three headers to function properly, which need to be forwarded by the
webserver.
* `X-Forwarded-Host` as which domain name the room is running (enforce strict TLS checking)
* `X-Forwarded-Proto` to ensure that TLS is used (and redirect if necessary)
* `X-Forwarded-For` the remote TCP/IP address of the client accessing the room (used for rate limiting)
* `X-Forwarded-For` the remote TCP/IP address of the client accessing the room (used for rate
limiting)
[nginx-example.conf](./nginx-example.conf) contains an [nginx](https://nginx.org) config that we use for [hermies.club](https://hermies.club). To get a wildcard TLS certificate you can follow the steps in [this article](https://medium.com/@alitou/getting-a-wildcard-ssl-certificate-using-certbot-and-deploy-on-nginx-15b8ffa34157), which uses the [certbot](https://certbot.eff.org/) utility.
[nginx-example.conf](./nginx-example.conf) contains an [nginx](https://nginx.org) config that
we use for [hermies.club](https://hermies.club). To get a wildcard TLS certificate you can
follow the steps in [this
article](https://medium.com/@alitou/getting-a-wildcard-ssl-certificate-using-certbot-and-deploy-on-nginx-15b8ffa34157),
which uses the [certbot](https://certbot.eff.org/) utility.

BIN
docs/screenshot.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 43 KiB