forked from ssbc/go-ssb-room
-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
reorganize the docs into deployment & development
- Loading branch information
Showing
14 changed files
with
132 additions
and
124 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,90 +1,2 @@ | ||
| # 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 and admin user sections 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). | ||
|
|
||
| A summary can be seen in the following chart: | ||
|
|
||
|  | ||
|
|
||
| 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". | ||
|
|
||
| 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). | ||
|
|
||
| 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). | ||
|
|
||
| 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) | ||
|
|
||
| [example-nginx.conf](./example-nginx.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. | ||
|
|
||
| # First Admin user | ||
|
|
||
| To manage your now working server, you need an initial admin user. For this you can use the "insert-user" utility included with go-ssb-room. | ||
| In a new terminal window navigate to the insert-user utility folder and compile the GO-based utility into an executable your computer can use | ||
|
|
||
| ``` | ||
| cd cmd/insert-user | ||
| go build | ||
| ``` | ||
|
|
||
| A new executable file should be created called "insert-user" | ||
| Execute the `./insert-user -h` command to get a full list of custom options (optional location of the repo & SQLite database and user role). follow the instructions given in the output you receive. | ||
|
|
||
| example (with custom repo location, only needed if you setup your with a custom repo): | ||
|
|
||
| ``` | ||
| ./insert-user -repo "/ssb-go-room-secrets" "@Bp5Z5TQKv6E/Y+QZn/3LiDWMPi63EP8MHsXZ4tiIb2w=.ed25519" | ||
| ``` | ||
|
|
||
| You can now login in the web-front-end using these credentials | ||
| - **Deployment** instructions are here: [deployment.md](./deployment.md) | ||
| - **Development** instructions are here: [development.md](./development.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,30 @@ | ||
| # 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). | ||
|
|
||
| A summary can be seen in the following chart: | ||
|
|
||
|  | ||
|
|
||
| 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". | ||
|
|
||
| A summary can be seen in the following chart: | ||
|
|
||
|  |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,71 @@ | ||
| # Getting Started | ||
| There are two paths to starting your own room: creating a build from source, or downloading one | ||
| of the premade releases. | ||
|
|
||
| ## Premade builds | ||
|
|
||
| See the [releases page](https://github.com/ssb-ngi-pointer/go-ssb-room/releases) for packaged linux releases. | ||
|
|
||
| We currently only distributed pre-packaged releases for Debian-compatible distributions. | ||
| See [Issue #79](https://github.com/ssb-ngi-pointer/go-ssb-room/issues/79) for the details. | ||
| If this doesn't work for you, read the "Creating a build" section below. | ||
|
|
||
| After running `sudo dpkg -i go-ssb-room_v1.2.3_Linux_x86_64.deb` pay special attention to the | ||
| [postinstall notes](./files/debian-postinstall.sh) for how to configure the systemd file and webserver. | ||
|
|
||
| ## 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` | ||
| * [Follow the development instructions](./development.md) | ||
| * You should now have a working go-ssb-room binary! Read the HTTP Hosting section below and admin | ||
| user sections below, for more instructions on the last mile. | ||
|
|
||
| # 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). | ||
|
|
||
| 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). | ||
|
|
||
| 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) | ||
|
|
||
| [example-nginx.conf](./files/example-nginx.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. | ||
|
|
||
| # First Admin user | ||
|
|
||
| To manage your now working server, you need an initial admin user. For this you can use the "insert-user" utility included with go-ssb-room. | ||
| In a new terminal window navigate to the insert-user utility folder and compile the GO-based utility into an executable your computer can use | ||
|
|
||
| ``` | ||
| cd cmd/insert-user | ||
| go build | ||
| ``` | ||
|
|
||
| A new executable file should be created called "insert-user" | ||
| Execute the `./insert-user -h` command to get a full list of custom options (optional location of the repo & SQLite database and user role). follow the instructions given in the output you receive. | ||
|
|
||
| example (with custom repo location, only needed if you setup your with a custom repo): | ||
|
|
||
| ``` | ||
| ./insert-user -repo "/ssb-go-room-secrets" "@Bp5Z5TQKv6E/Y+QZn/3LiDWMPi63EP8MHsXZ4tiIb2w=.ed25519" | ||
| ``` | ||
|
|
||
| You can now login in the web-front-end using these credentials |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes
File renamed without changes.
File renamed without changes
File renamed without changes