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.

173 lines
4.6 KiB

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. # Developing on go-neb.
  125. There's a bunch more tools this project uses when developing in order to do
  126. things like linting. Some of them are bundled with go (fmt and vet) but some
  127. are not. You should install the ones which are not:
  128. ```bash
  129. go get github.com/golang/lint/golint
  130. go get github.com/fzipp/gocyclo
  131. ```
  132. You can then install the pre-commit hook:
  133. ```bash
  134. ./hooks/install.sh
  135. ```
  136. ## Viewing the API docs.
  137. ```
  138. # Start a documentation server listening on :6060
  139. GOPATH=$GOPATH:$(pwd) godoc -v -http=localhost:6060 &
  140. # Open up the documentation for go-neb in a browser.
  141. sensible-browser http://localhost/pkg/github.com/matrix-org/go-neb
  142. ```