You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Buzzer is a Laravel app that establishes a mean of communication between different projects by leveraging the [publish/subscribe pattern](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern).
6
8
7
9
At the moment buzzer's authentication is setup to rely on Zanichelli's own IDP for authentication, but you can still test the app without authenticating.
8
10
9
-
# Table of Contents
11
+
##Table of Contents
10
12
11
-
-[Setup](#setup)
12
-
-[GUI](#gui)
13
-
-[Usage](#usage)
14
-
-[Testing](#testing)
15
-
-[API Documentation](#api-documentation)
16
-
-[Logs](#logs)
17
-
-[Infrastructure as Code](#infrastructure-as-code)
18
-
-[How to contribute](#how-to-contribute)
13
+
-[Setup](#setup)
14
+
-[GUI](#gui)
15
+
-[Usage](#usage)
16
+
-[Testing](#testing)
17
+
-[API Documentation](#api-documentation)
18
+
-[Logs](#logs)
19
+
-[Infrastructure as Code](#infrastructure-as-code)
20
+
-[How to contribute](#how-to-contribute)
19
21
20
-
# Setup
22
+
##Setup
21
23
22
24
Please note that **steps 2 to 5** are **optional** (but recommended). Follow them if you want to use **Docker containers** for local development.
2.Copy env.example to .env and fill the empty fields.
30
+
2. Copy env.example to .env and fill the empty fields.
29
31
30
32
1. If you want to try the app without authenticating, set `USE_ZANICHELLI_IDP=false`
31
33
32
34
3. From the project's root folder, build your Docker images with `make rebuild` or:
33
35
34
-
`docker-compose -f docker-compose.dev.yml up --build -d`
36
+
`docker-compose -f docker-compose.dev.yml up --build -d`
35
37
36
-
4.You must run the next few commands _inside_ the app's container. To enter the container, use `make shell` or:
38
+
4. You must run the next few commands _inside_ the app's container. To enter the container, use `make shell` or:
37
39
38
-
`docker exec -it buzzer_app bash`
40
+
`docker exec -it buzzer_app bash`
39
41
40
-
5.Install the required dependencies with composer
42
+
5. Install the required dependencies with composer
41
43
42
-
`composer install`
44
+
`composer install`
43
45
44
-
6.Generate a random application key
46
+
6. Generate a random application key
45
47
46
-
`php artisan key:generate`
48
+
`php artisan key:generate`
47
49
48
50
7. Generate passport keys
49
51
50
-
`php artisan passport:keys`
52
+
`php artisan passport:keys`
51
53
52
54
8. To aid with development, you can also publish telescope assets
53
55
54
-
`php artisan telescope:publish`
56
+
`php artisan telescope:publish`
55
57
56
58
9. Launch migrations and seeders to create and populate the database tables
57
59
58
-
`php artisan migrate --seed`
60
+
`php artisan migrate --seed`
59
61
60
-
10.Exit the container shell with *ctrl+D* / *cmd+D* then run:
62
+
10. Exit the container shell with _ctrl+D_ / _cmd+D_ then run:
61
63
-`make npm_install`
62
64
-`make npm_run`
63
65
64
-
## Accessing services
66
+
###Accessing services
65
67
66
-
-**Web** the frontend admin app: http://localhost:8085
68
+
-**Web** the frontend admin app: <http://localhost:8085>
67
69
68
-
-**phpMyAdmin**: http://localhost:8086
70
+
-**phpMyAdmin**: <http://localhost:8086>
69
71
70
-
-**Telescope**: http://localhost:8085/telescope
72
+
-**Telescope**: <http://localhost:8085/telescope>
71
73
72
-
## Starting and stopping containers
74
+
###Starting and stopping containers
73
75
74
76
Once created, the containers can be **started** anytime with `make up` or with the following command:
75
77
@@ -83,123 +85,123 @@ To off and remove container services, use `make down` or:
83
85
84
86
`docker-compose -f docker-compose.dev.yml down`
85
87
86
-
# GUI
88
+
##GUI
87
89
88
90
The app consists of four main views
89
91
90
-
## Publishers
92
+
###Publishers
91
93
92
94
Here you can manage all the publishers authorized to use your app. To create a publisher you need to provide:
93
95
94
-
-a meaningful name
95
-
-the host from which the publisher will call buzzer
96
-
-a username for the basic auth protecting incoming calls
96
+
- a meaningful name
97
+
- the host from which the publisher will call buzzer
98
+
- a username for the basic auth protecting incoming calls
97
99
98
100
Once you create a publisher the app will provide you with a password for the basic auth.
99
101
100
-
## Subscribers
102
+
###Subscribers
101
103
102
104
Here you can manage all the subscribers buzzer can contact. To create a subscriber you need to provide:
103
105
104
-
-a menaningful name
105
-
-the host buzzer needs to call.
106
+
- a menaningful name
107
+
- the host buzzer needs to call.
106
108
107
109
Please note you only need to specify the host at this time, not the full endpoint.
108
110
109
-
## Channels
111
+
###Channels
110
112
111
113
Here you can find and inspect all the configured channels. To create a channel you need to provide:
112
114
113
-
-a meaningful name
114
-
-the channel's priority. Buzzer will look at this value to determine in what order it needs to dispatch incoming messages.
115
+
- a meaningful name
116
+
- the channel's priority. Buzzer will look at this value to determine in what order it needs to dispatch incoming messages.
115
117
116
118
By hitting the edit button on an existing channel you can access and manage the full list of publishers and subscribers interacting with the channel.
117
119
Here is where you can configure the exact endpoints for your subscribers.
118
120
119
-
## Failed Jobs
121
+
###Failed Jobs
120
122
121
123
Here you'll find a list of all failed jobs, with an option to retry or delete them. You can do this either for single jobs or for all failed jobs at once.
122
124
123
-
# Usage
125
+
##Usage
124
126
125
127
To get a feel for how the app works, you can follow the next few steps for a quick test run from the GUI.
126
128
The following guide assumes you already completed the steps outlined in the [Setup](#setup) section and buzzer is currently running.
127
129
128
-
1.if you open the app at http://localhost:8085, you'll notice there's already one channel, named "me". We'll send our message to this channel.
129
-
2.open another terminal in the project root and use either `make shell` or `docker exec -it buzzer_app bash` to enter the app's container.
130
-
1.run `php artisan queue:work` and leave the terminal open. This will ensure our message gets processed.
131
-
3.inside /storage/logs you will find a file with today's date. Open it; we'll need it later. If you don't see it, don't worry. It will materialize as soon as the first log is generated.
132
-
4.open http://localhost:8085/api/documentation
133
-
1.search for /api/sendMessage and open it
134
-
2.hit "Try it out" and a few more fields and controls will appear
135
-
3.edit the request body so that the value for `"channel"` matches an existing channel. In our case, `"channel": "me"`
136
-
4.hit "Execute"
137
-
5.fill out the basic auth form using credentials from the test publisher: "test" and "pwd"
138
-
5.we just sent our message to the three test APIs listed as subscribers for our channel!
139
-
6.looking at the log file from step 3, notice how three logs have appeared. They're the result of a call to three different APIs. See the [#channels](#channels) section of the GUI for more information.
140
-
141
-
# Testing
130
+
1. if you open the app at <http://localhost:8085>, you'll notice there's already one channel, named "me". We'll send our message to this channel.
131
+
2. open another terminal in the project root and use either `make shell` or `docker exec -it buzzer_app bash` to enter the app's container.
132
+
1. run `php artisan queue:work` and leave the terminal open. This will ensure our message gets processed.
133
+
3. inside /storage/logs you will find a file with today's date. Open it; we'll need it later. If you don't see it, don't worry. It will materialize as soon as the first log is generated.
134
+
4. open <http://localhost:8085/api/documentation>
135
+
1. search for /api/sendMessage and open it
136
+
2. hit "Try it out" and a few more fields and controls will appear
137
+
3. edit the request body so that the value for `"channel"` matches an existing channel. In our case, `"channel": "me"`
138
+
4. hit "Execute"
139
+
5. fill out the basic auth form using credentials from the test publisher: "test" and "pwd"
140
+
5. we just sent our message to the three test APIs listed as subscribers for our channel!
141
+
6. looking at the log file from step 3, notice how three logs have appeared. They're the result of a call to three different APIs. See the [#channels](#channels) section of the GUI for more information.
142
+
143
+
##Testing
142
144
143
145
You can run tests using the PHPUnit binary located in the vendor directory
144
146
145
147
- Run all tests
146
-
-`docker exec -it buzzer_app vendor/bin/phpunit` or `make run_tests`
148
+
-`docker exec -it buzzer_app vendor/bin/phpunit` or `make run_tests`
147
149
148
150
- Run every method of a specific test class
149
-
-`docker exec -it buzzer_app vendor/bin/phpunit tests/Feature/TestClassName` or `make run_tests tests/Feature/TestClassName`
151
+
-`docker exec -it buzzer_app vendor/bin/phpunit tests/Feature/TestClassName` or `make run_tests tests/Feature/TestClassName`
Once you've built your containers, the swagger documentation is available at http://localhost:8085/api/documentation
175
+
Once you've built your containers, the swagger documentation is available at <http://localhost:8085/api/documentation>
174
176
175
-
# Logs
177
+
##Logs
176
178
177
179
Buzzer includes a filebeat instance that is set up to communicate with a logstash pipeline.
178
180
If you or your organization have a running logstash instance, you can connect it by changing the `hosts` IP/port inside the .yml files in `docker/filebeat`
179
181
180
-
# Infrastructure as Code
182
+
##Infrastructure as Code
181
183
182
184
We use terraform, jenkins and ansible to manage our infrastructure on AWS via code.
183
185
184
186
As terraform configurations were highly customized to address our specific needs, we decided to exclude them from the current repository to avoid unnecessary clutter.
185
187
186
-
## Jenkins
188
+
###Jenkins
187
189
188
190
You need to add the following build parameters to your jenkins pipeline:
189
191
190
-
-`deploy_branch`: the branch you're deploying
191
-
-`aws_account`: the ID of your AWS account
192
+
-`deploy_branch`: the branch you're deploying
193
+
-`aws_account`: the ID of your AWS account
192
194
193
195
Our pipelines are configured to act on AWS through the `ContinuousIntegrationAccessRole` role on the provided account. You should set up a similar role or change the name inside the jenkinsfiles.
194
196
195
197
Feel free to also change the region, which is currently setup as `eu-west-1`.
196
198
197
-
# How to Contribute
199
+
##How to Contribute
198
200
199
-
## Did you find a bug?
201
+
###Did you find a bug?
200
202
201
-
-**Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/ZanichelliEditore/buzzer/issues).
203
+
-**Ensure the bug was not already reported** by searching on GitHub under [Issues](https://github.com/ZanichelliEditore/buzzer/issues).
202
204
203
-
-If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/ZanichelliEditore/buzzer/issues/new). Be sure to include a **title and clear description**, as much relevant information as possible and, wherever possible, a **code sample** demonstrating the expected behavior that is not occurring.
205
+
- If you're unable to find an open issue addressing the problem, [open a new one](https://github.com/ZanichelliEditore/buzzer/issues/new). Be sure to include a **title and clear description**, as much relevant information as possible and, wherever possible, a **code sample** demonstrating the expected behavior that is not occurring.
204
206
205
-
-We expect all who interact with the project to follow the [Contributor Covenant Code of Conduct](https://github.com/ZanichelliEditore/buzzer/blob/master/CODE-OF-CONDUCT.md)
207
+
- We expect all who interact with the project to follow the [Contributor Covenant Code of Conduct](https://github.com/ZanichelliEditore/buzzer/blob/master/CODE-OF-CONDUCT.md)
0 commit comments