Merge pull request #204 from ssb-ngi-pointer/update-readme

Update documentation, add screenshot

README.md

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

docs/README.md

@@ -1,36 +1,69 @@
+# 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 [email protected]: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:
 
 ![Chart](./login-chart.png)
 
 # 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)
-
-[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. 
+* `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.