README.md 4.31 KB
Newer Older
Dimitra Chatzichrysou's avatar
Dimitra Chatzichrysou committed
1
2
3
4
5
6
7
# Notifications Routing

## Contribute

* Locally clone the repository

```bash
Carina Antunes's avatar
Carina Antunes committed
8
$ git clone ssh://git@gitlab.cern.ch:7999/push-notifications/notifications-routing.git
Dimitra Chatzichrysou's avatar
Dimitra Chatzichrysou committed
9
10
11
12
13
14
15
16
17
18
$ cd notifications-routing
```

* Make sure you have the latest version

```bash
$ git checkout master
$ git pull
```

Carina Antunes's avatar
Carina Antunes committed
19
20
21
* Install [pre-commit](https://pre-commit.com/#install) hooks

## Develop with docker-compose
Caetan Tojeiro Carpente's avatar
Caetan Tojeiro Carpente committed
22
23
24

This is the recommended method for Linux distributions.

Carina Antunes's avatar
Carina Antunes committed
25
26
27
### Dependencies
- [Docker](https://docs.docker.com/engine/install/)
- [Docker-compose](https://docs.docker.com/compose/install/)
Dimitra Chatzichrysou's avatar
Dimitra Chatzichrysou committed
28

Carina Antunes's avatar
Carina Antunes committed
29
30
31
### Instructions

- Start the routing container, Postgres and ActiveMQ
Dimitra Chatzichrysou's avatar
Dimitra Chatzichrysou committed
32
```bash
Carina Antunes's avatar
Carina Antunes committed
33
34
35
36
$ make docker-build-env
```

There is a `subscriber` client that listens to messages and a helper utility called `publisher` that sends messages.
Dimitra Chatzichrysou's avatar
Dimitra Chatzichrysou committed
37

38
For the `subscriber`, it will run automatically as it is the container's entrypoint.
Caetan Tojeiro Carpente's avatar
Caetan Tojeiro Carpente committed
39
40
41
42

For the `publisher` to send one message, it's necessary to open another terminal and enter the container:

- Enter the routing container
Dimitra Chatzichrysou's avatar
Dimitra Chatzichrysou committed
43
```bash
Caetan Tojeiro Carpente's avatar
Caetan Tojeiro Carpente committed
44
$ make docker-shell-env  # To enter the container
45
46
47
```
A message send can be triggered using the `docker-send.py` script.
```
48
$ python scripts/docker-send.py # To send one message
Dimitra Chatzichrysou's avatar
Dimitra Chatzichrysou committed
49
```
50
51
52
53
54
55
56
57
58
The payload can also be customized with the following arguments:
```
usage: docker-send.py [-h] [-l] [-c] [-e E] [-ci CI] [-ni NI]
-l          use to connect to localhost instead of activemq
-c          use to send an email with Category
-e E        use to set a target email username
-ci CI      use to set a target channel id
-ni NI      use to set a target notification id
```
Dimitra Chatzichrysou's avatar
Dimitra Chatzichrysou committed
59

Caetan Tojeiro Carpente's avatar
Caetan Tojeiro Carpente committed
60
61
To test the set up, it is possible to see the message in [ActiveMQ's admin UI](http://localhost:8161/admin/queues.jsp)

Carina Antunes's avatar
Carina Antunes committed
62
- Clean up the containers
Dimitra Chatzichrysou's avatar
Dimitra Chatzichrysou committed
63
```bash
Carina Antunes's avatar
Carina Antunes committed
64
$ make docker-stop
Dimitra Chatzichrysou's avatar
Dimitra Chatzichrysou committed
65
66
```

Caetan Tojeiro Carpente's avatar
Caetan Tojeiro Carpente committed
67

68
### Known issues (and solutions) for some Linux distributions
Caetan Tojeiro Carpente's avatar
Caetan Tojeiro Carpente committed
69
70
71

- If you have some service (probably postgres) running locally in your machine at port 5432 you have 2 options:
  - Stop your local service
72
  - Change the external port to a free port (i.e. 5433) at ```docker-compose.full.yml```
Caetan Tojeiro Carpente's avatar
Caetan Tojeiro Carpente committed
73
74
75
76
77
78
79
80
81
82
83
84
85
86
    ```
      pg_db:
      ...
      ports:
        - 5433:5432
        ...
    ```
- If the container is not able to connect/find the service:
  - [Disable SELinux](https://www.cyberciti.biz/faq/disable-selinux-on-centos-7-rhel-7-fedora-linux/)
  - [Whitelist docker in firewall](https://fedoramagazine.org/docker-and-fedora-32/) or using Firewall tool from Software store
      ```bash
      $ sudo firewall-cmd --permanent --zone=trusted --add-interface=docker0
      $ sudo firewall-cmd --permanent --zone=FedoraWorkstation --add-masquerade
      ```
Dimitra Chatzichrysou's avatar
Dimitra Chatzichrysou committed
87

Carina Antunes's avatar
Carina Antunes committed
88
89
90
91
92
93
94
95
### Generic Guidelines

* Acessing ActiveMQ Admin UI:
For accessing the local instance of `ActiveMQ`:  http://localhost:8161/admin

```
User: admin
Password: admin
Dimitra Chatzichrysou's avatar
Dimitra Chatzichrysou committed
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
```

* Develop, test and finish the new feature with regular commits

```bash
$ git add file1 file2
$ git commit
...
$ git push
```

* When ready, rebase interactively against the latest `master` to tidy things up and then create a merge request

```bash
$ git checkout master
$ git pull
$ git checkout dev_short_feature_description
$ git rebase -i master
$ git push
```

[Create a merge request](https://gitlab.cern.ch/push-notifications/notifications-routing/-/merge_requests) from the `dev` branch into `master`. Assign a reviewer. Following a discussion and approval from the reviewer, the merge request can be merged.
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140


### Manage dependencies
We're using [poetry](https://python-poetry.org/docs/cli/) to manage dependencies

:warning:
Only update dependencies inside the docker container, ie. after running `make docker-shell-env`.

- Regenerate lock after manually changing `pyproject.toml`:
```bash
poetry lock
```

- Add a dependency with:
```bash
poetry add "pendulum~2.0.5"
```
See more on choosing [dependency constrains](https://python-poetry.org/docs/versions/).

- Update a dependency:
```bash
poetry update requests
```
141

142
### Creating and Running Unit and Integration Tests
143
144
145

#### Writing tests

146
The folder ```tests```  contains all test cases and future tests should be placed into this folder.
147
148
149
Each test file needs to start with the prefix ```test_``` (e.g. ```test_utils.py```)


150
Tests functions always start with the prefix ```test_``` e.g.:
151
152
153
154
155
156
157
```python

def test_FUNCTION_OPERATION(self):
    ...

```

158
#### Execute Pytest Tests
159
160
161
162

To manually execute the tests use the following command:

```bash
163
make ci-test
164
```