You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

269 lines
8.4 KiB

8 years ago
8 years ago
  1. # Building go-neb
  2. Go-neb is built using `gb` (https://getgb.io/). To build go-neb:
  3. ```bash
  4. # Install gb
  5. go get github.com/constabulary/gb/...
  6. # Clone the go-neb repository
  7. git clone https://github.com/matrix-org/go-neb
  8. cd go-neb
  9. # Build go-neb
  10. gb build github.com/matrix-org/go-neb
  11. ```
  12. # Running go-neb
  13. Go-neb uses environment variables to configure its database and bind address.
  14. To run go-neb:
  15. BIND_ADDRESS=:4050 DATABASE_TYPE=sqlite3 DATABASE_URL=go-neb.db BASE_URL=https://public.facing.endpoint bin/go-neb
  16. Go-neb needs to connect as a matrix user to receive messages. Go-neb can listen
  17. for messages as multiple matrix users. The users are configured using an
  18. HTTP API and the config is stored in the database. Go-neb will automatically
  19. start syncing matrix messages when the user is configured. To create a user:
  20. curl -X POST localhost:4050/admin/configureClient --data-binary '{
  21. "UserID": "@goneb:localhost:8448",
  22. "HomeserverURL": "http://localhost:8008",
  23. "AccessToken": "<access_token>"
  24. }'
  25. {
  26. "OldClient": {},
  27. "NewClient": {
  28. "UserID": "@goneb:localhost:8448",
  29. "HomeserverURL": "http://localhost:8008",
  30. "AccessToken": "<access_token>"
  31. }
  32. }
  33. Services in go-neb listen for messages in particular rooms using a given matrix
  34. user. Services are configured using an HTTP API and the config is stored in the
  35. database. Services use one of the matrix users configured on go-neb to receive
  36. matrix messages. Each service is configured to listen for messages in a set
  37. of rooms. Go-neb will automatically join the service to its rooms when it is
  38. configured. To start an echo service:
  39. curl -X POST localhost:4050/admin/configureService --data-binary '{
  40. "Type": "echo",
  41. "Id": "myserviceid",
  42. "Config": {
  43. "UserID": "@goneb:localhost:8448",
  44. "Rooms": ["!QkdpvTwGlrptdeViJx:localhost:8448"]
  45. }
  46. }'
  47. {
  48. "Type": "echo",
  49. "Id": "myserviceid",
  50. "OldConfig": {},
  51. "NewConfig": {
  52. "UserID": "@goneb:localhost:8448",
  53. "Rooms": ["!QkdpvTwGlrptdeViJx:localhost:8448"]
  54. }
  55. }
  56. Go-neb has a heartbeat listener that returns 200 OK so that load balancers can
  57. check that the server is still running.
  58. curl -X GET localhost:4050/test
  59. {}
  60. ## Starting a Github Service
  61. ### Register a Github realm
  62. ```
  63. curl -X POST localhost:4050/admin/configureAuthRealm --data-binary '{
  64. "ID": "mygithubrealm",
  65. "Type": "github",
  66. "Config": {
  67. "ClientSecret": "YOUR_CLIENT_SECRET",
  68. "ClientID": "YOUR_CLIENT_ID",
  69. "RedirectBaseURI": "https://public.path.to.neb"
  70. }
  71. }'
  72. ```
  73. Returns:
  74. ```
  75. {
  76. "ID":"mygithubrealm",
  77. "Type":"github",
  78. "OldConfig":null,
  79. "NewConfig":{
  80. "ClientSecret":"YOUR_CLIENT_SECRET",
  81. "ClientID":"YOUR_CLIENT_ID",
  82. "RedirectBaseURI":"https://public.path.to.neb"
  83. }
  84. }
  85. ```
  86. ### Make a request for Github Auth
  87. ```
  88. curl -X POST localhost:4050/admin/requestAuthSession --data-binary '{
  89. "RealmID": "mygithubrealm",
  90. "UserID": "@your_user_id:localhost",
  91. "Config": {
  92. }
  93. }'
  94. ```
  95. Returns:
  96. ```
  97. {
  98. "URL":"https://github.com/login/oauth/authorize?client_id=$ID\u0026client_secret=$SECRET\u0026redirect_uri=$REDIRECT_BASE_URI%2Frealms%2Fredirects%2Fmygithubrealm\u0026state=$RANDOM_STRING"
  99. }
  100. ```
  101. Follow this link and grant access for NEB to act on your behalf.
  102. ### Create a github bot
  103. ```
  104. curl -X POST localhost:4050/admin/configureService --data-binary '{
  105. "Type": "github",
  106. "Id": "mygithubserviceid",
  107. "Config": {
  108. "RealmID": "mygithubrealm",
  109. "BotUserID": "@goneb:localhost",
  110. "ClientUserID": "@example:localhost",
  111. "Rooms": {
  112. "!EmwxeXCVubhskuWvaw:localhost": {
  113. "Repos": {
  114. "owner/repo": {
  115. "Events": ["push","issues"]
  116. }
  117. }
  118. }
  119. }
  120. }
  121. }'
  122. ```
  123. This request will make `BotUserID` join the `Rooms` specified and create webhooks for the `owner/repo` projects given.
  124. ## Starting a JIRA Service
  125. ### Register a JIRA realm
  126. Generate an RSA private key: (JIRA does not support key sizes >2048 bits)
  127. ```bash
  128. openssl genrsa -out privkey.pem 2048
  129. cat privkey.pem
  130. ```
  131. Create the realm:
  132. ```
  133. curl -X POST localhost:4050/admin/configureAuthRealm --data-binary '{
  134. "ID": "jirarealm",
  135. "Type": "jira",
  136. "Config": {
  137. "JIRAEndpoint": "matrix.org/jira/",
  138. "ConsumerName": "goneb",
  139. "ConsumerKey": "goneb",
  140. "ConsumerSecret": "random_long_string",
  141. "PrivateKeyPEM": "-----BEGIN RSA PRIVATE KEY-----\r\nMIIEowIBAAKCAQEA39UhbOvQHEkBP9fGnhU+eSObTWBDGWygVYzbcONOlqEOTJUN\r\n8gmnellWqJO45S4jB1vLLnuXiHqEWnmaShIvbUem3QnDDqghu0gfqXHMlQr5R8ZP\r\norTt1F2idWy1wk5rVXeLKSG7uriYhDVOVS69WuefoW5v55b5YZV283v2jROjxHuj\r\ngAsJA7k6tvpYiSXApUl6YHmECfBoiwG9bwItkHwhZ\/fG9i4H8\/aOyr3WlaWbVeKX\r\n+m38lmYZvzQFRAk5ab1vzCGz4cyc\r\nTk2qmZpcjHRd1ijcOkgC23KF8lHWF5Zx0tySR+DWL1JeGm8NJxKMRJZuE8MIkJYF\r\nryE7kjspNItk6npkA3\/A4PWwElhddI4JpiuK+29mMNipRcYYy9e0vH\/igejv7ayd\r\nPLCRMQKBgBDSNWlZT0nNd2DXVqTW9p+MG72VKhDgmEwFB1acOw0lpu1XE8R1wmwG\r\nZRl\/xzri3LOW2Gpc77xu6fs3NIkzQw3v1ifYhX3OrVsCIRBbDjPQI3yYjkhGx24s\r\nVhhZ5S\/TkGk3Kw59bDC6KGqAuQAwX9req2l1NiuNaPU9rE7tf6Bk\r\n-----END RSA PRIVATE KEY-----"
  142. }
  143. }'
  144. ```
  145. Returns:
  146. ```json
  147. {
  148. "ID": "jirarealm",
  149. "Type": "jira",
  150. "OldConfig": null,
  151. "NewConfig": {
  152. "JIRAEndpoint": "https://matrix.org/jira/",
  153. "Server": "Matrix.org",
  154. "Version": "6.3.5a",
  155. "ConsumerName": "goneb",
  156. "ConsumerKey": "goneb",
  157. "ConsumerSecret": "random_long_string",
  158. "PublicKeyPEM": "-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA39UhbOvQHEkBP9fGnhU+\neSObTWBDGWygVYzbcONOlqEOTJUN8gmnellWqJO45S4jB1vLLnuXiHqEWnmaShIv\nbUem3QnDDqghu0gfqXHMlQr5R8ZPorTt1F2idWy1wk5rVXeLKSG7uriYhDVOVS69\nWuefoW5v55b5YZV283v2jROjxHujgAsJA7k6tvpYiSXApUl6YHmECfBoiwG9bwIt\nkHwhZ/fG9i4H8/aOyr3WlaWbVeKX+m38lmYZvzQFRd7UPU7DuO6Aiqj7RxrbAvqq\ndPeoAvo6+V0TRPZ8YzKp2yQmDcGH69IbuKJ2BG1Qx8znZAvghKQ6P9Im+M4c7j9i\ndwIDAQAB\n-----END PUBLIC KEY-----\n",
  159. "PrivateKeyPEM": "-----BEGIN RSA PRIVATE KEY-----\r\nMIIEowIBAAKCAQEA39UhbOvQHEkBP9fGnhU+eSObTWBDGWygVYzbcONOlqEOTJUN\r\n8gmnellWqJO45S4jB1vLLnuXiHqEWnmaShIvbUem3QnDDqghu0gfqXHMlQr5R8ZP\r\norTt1F2idWy1wk5rVXeLKSG7uriYhDVOVS69WuefoW5v55b5YZV283v2jROjxHuj\r\ngAsJA7k6tvpYiSXApUl6YHmECfBoiwG9bwItkHwhZ/fG9i4H8/aOyr3WlaWbVeKX\r\n+m38lmYZvzQFRd7UPU7DuO6Aiqj7RxrbAvqqdPeoAvo6+V0TRPZ8YzKp2yQmDcGH\r\n69IbuKJ2BG1Qx8znZAvghKQ6P9Im+M4c7j9iMG72VKhDgmEwFB1acOw0lpu1XE8R1wmwG\r\nZRl/xzri3LOW2Gpc77xu6fs3NIkzQw3v1ifYhX3OrVsCIRBbDjPQI3yYjkhGx24s\r\nVhhZ5S/TkGk3Kw59bDC6KGqAuQAwX9req2l1NiuNaPU9rE7tf6Bk\r\n-----END RSA PRIVATE KEY-----"
  160. }
  161. }
  162. ```
  163. The `ConsumerKey`, `ConsumerSecret`, `ConsumerName` and `PublicKeyPEM` must be manually inserted
  164. into the "Application Links" section under JIRA Admin Settings by a JIRA admin on the target
  165. JIRA installation. Once that is complete, users can OAuth on the target JIRA installation.
  166. ### Make a request for JIRA Auth
  167. ```
  168. curl -X POST localhost:4050/admin/requestAuthSession --data-binary '{
  169. "RealmID": "jirarealm",
  170. "UserID": "@example:localhost",
  171. "Config": {
  172. }
  173. }'
  174. ```
  175. Returns:
  176. ```json
  177. {
  178. "URL":"https://jira.somewhere.com/plugins/servlet/oauth/authorize?oauth_token=7yeuierbgweguiegrTbOT"
  179. }
  180. ```
  181. Follow this link and grant access for NEB to act on your behalf.
  182. ### Create a JIRA bot
  183. ```
  184. curl -X POST localhost:4050/admin/configureService --data-binary '{
  185. "Type": "jira",
  186. "Id": "jid",
  187. "Config": {
  188. "BotUserID": "@goneb:localhost",
  189. "ClientUserID": "@example:localhost",
  190. "Rooms": {
  191. "!EmwxeXCVubhskuWvaw:localhost": {
  192. "RealmID": "jirarealm",
  193. "Projects": {
  194. "BOTS": {
  195. "Expand": true,
  196. "Track": true
  197. }
  198. }
  199. }
  200. }
  201. }
  202. }'
  203. ```
  204. # Developing on go-neb.
  205. There's a bunch more tools this project uses when developing in order to do
  206. things like linting. Some of them are bundled with go (fmt and vet) but some
  207. are not. You should install the ones which are not:
  208. ```bash
  209. go get github.com/golang/lint/golint
  210. go get github.com/fzipp/gocyclo
  211. ```
  212. You can then install the pre-commit hook:
  213. ```bash
  214. ./hooks/install.sh
  215. ```
  216. ## Viewing the API docs.
  217. ```
  218. # Start a documentation server listening on :6060
  219. GOPATH=$GOPATH:$(pwd) godoc -v -http=localhost:6060 &
  220. # Open up the documentation for go-neb in a browser.
  221. sensible-browser http://localhost/pkg/github.com/matrix-org/go-neb
  222. ```