Skip to content

Commit 1d9e5d3

Browse files
gsanchiettigsanchietti
committed
doc: improve deploy and readme
1 parent 7c4e604 commit 1d9e5d3

File tree

2 files changed

+51
-81
lines changed

2 files changed

+51
-81
lines changed

‎README.md‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -77,8 +77,13 @@ Limitations:
7777
- when a private room is deleted, there is no way to send messages to the user
7878
- text-only messages are supported (no media, no rich content)
7979
- only one-to-one direct messaging is supported (no group chats)
80+
- before using the chat from the app, users who receive or send must have logged into Matrix at least once using an official client (Cinny or Element)
8081

8182
The following features are not yet implemented:
8283

8384
- Account removal: https://doc.acrobits.net/api/client/account_removal_reporter.html#account-removal-reporter-webservice
84-
- Messages with media content
85+
- Messages with media content:
86+
- https://doc.acrobits.net/api/client/x-acro-filetransfer.html
87+
- https://doc.acrobits.net/api/client/decryption.html
88+
- https://doc.acrobits.net/mmmsg/index.html
89+
- The *Rich Messaging* feature must be enabled inside Acrobits app

‎docs/DEPLOY.md‎

Lines changed: 45 additions & 80 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,18 @@ The deploy consists of two main steps:
66

77
## Acrobits
88

9-
Substutute `synapse.gs.nethserver.net` with your Matrix homeserver name.
9+
Replace `synapse.gs.nethserver.net` with your Matrix homeserver name.
10+
11+
The following features must be enabled:
12+
- *Incoming and Outgoing Messages via Web Service*
13+
- *Rich Messaging*, needed only to allow to send attachments (not implemented yet)
14+
15+
Automatic provisioning:
16+
17+
- deploy `ctiapp-authproxy` from the [this PR](https://github.com/nethesis/ctiapp-authproxy/pull/16)
18+
- set the deployed hostname inside the **External provisioning** field
19+
20+
As an alternative to automatic provisioning, manual provisioning options:
1021

1122
- **General Messaging Configuration**: select on **Web Service** datasource
1223
- **Outgoing SMS via Web Service**:
@@ -26,96 +37,50 @@ Substutute `synapse.gs.nethserver.net` with your Matrix homeserver name.
2637

2738
To function correctly, the proxy must be registered as an Application Service with your Synapse homeserver.
2839

29-
## Manual setup on an existing NS8 installation
40+
The following configurations are required:
41+
- a create a registration YAML file (e.g., `acrobits-proxy.yaml`): this file tells Synapse how to communicate with the proxy
42+
- an updated `homeserver.yaml` to include the Application Service registration file
43+
- a route to `/m2a` in traefik to point to the proxy
44+
- a route to `/_matrix/push/v1/notify` in traefik to point to the proxy (for push notifications)
3045

31-
Install matrix:
32-
```
33-
add-module ghcr.io/nethserver/matrix:latest
34-
```
46+
Everything is already implemented inside [ns8-matrix](https://github.com/NethServer/ns8-matrix) module.
3547

36-
Enter the matrix user shell:
37-
```
38-
runagent -m matrix1
39-
```
48+
### Matrix <-> Acrobits Mobile App Integration Testing
4049

41-
Download the container image:
42-
```
43-
podman pull ghcr.io/nethesis/matrix2acrobits:latest
44-
```
50+
This is the current procedure to test the integration.
4551

46-
First, create a registration YAML file (e.g., `acrobits-proxy.yaml`) and place it on your homeserver. This file tells Synapse how to communicate with the proxy.
47-
```
48-
cat <<EOF >synapse-config/acrobits-proxy.yaml
49-
id: acrobits-proxy
50-
url: http://localhost:8080
51-
as_token: "secret"
52-
hs_token: "secret"
53-
sender_localpart: _acrobits_proxy
54-
namespaces:
55-
users:
56-
- exclusive: false
57-
regex: '@.*'
58-
aliases:
59-
- exclusive: false
60-
regex: '.*'
61-
rooms:
62-
- exclusive: false
63-
regex: '.*'
64-
EOF
65-
```
52+
### Users
6653

67-
Next, add the path to your registration file to your Synapse `homeserver.yaml`:
54+
1. Install a local LDAP domain.
55+
2. Create at least two users (`user1` and `user2`).
6856

69-
```
70-
echo "app_service_config_files:" >> ../templates/synapse-homeserver.yaml
71-
echo " - /data/config/acrobits-proxy.yaml" >> ../templates/synapse-homeserver.yaml
72-
```
57+
### Matrix
7358

74-
You must generate your own secure random strings for `as_token` and `hs_token`.
59+
1. Install Matrix on NethServer 8: `add-module ghcr.io/nethserver/matrix:latest` (will be available in the forge soon).
60+
2. Configure Matrix using the UI; leave the NethVoice-related field empty (we will configure it later).
61+
3. Enable at least one client (I recommend Cinny as it is simpler).
62+
4. Log in with `user1` and `user2` on the Matrix client.
7563

76-
Restart the service:
77-
```
78-
systemctl --user restart synapse
79-
```
64+
### NethVoice
8065

81-
Start the matrix2acrobits container:
82-
```
83-
podman run -d --rm --replace --name matrix2acrobits --network host -e LOGLEVEL=debug -e MATRIX_HOMESERVER_URL=https://synapse.gs.nethserver.net -e MATRIX_AS_TOKEN=secret -e PROXY_PORT=8080 -e AS_USER_ID=@_acrobits_proxy:synapse.gs.nethserver.net -e PROXY_URL=https://synapse.gs.nethserver.net/ -e EXT_AUTH_URL=https://voice.gs.nethserver.net/freepbx/rest/testextauth ghcr.io/nethesis/matrix2acrobits
66+
1. Install the experimental version of NethVoice: `add-module ghcr.io/nethesis/nethvoice:matrix_integration`.
67+
2. Configure NethVoice by associating it with the LDAP domain created above.
68+
3. Configure the two users in the wizard, ensuring you assign the mobile app extension to both.
69+
4. Configure the Matrix integration:
70+
Retrieve the Matrix UUID: `redis-cli hget module/matrix1/environment MODULE_UUID`, and use it in the command below:
71+
```bash
72+
api-cli run module/nethvoice1/set-matrix-server --data '{"module_uuid": "cf50b191-95d5-435b-bf34-0905bf7dba55"}'
8473
```
8574

86-
Configure traefik to route /m2a to the proxy:
87-
```
88-
api-cli run set-route --agent module/traefik1 --data '{"instance": "matrix1-m2a", "name":"synapse-m2a","host":"synapse.gs.nethserver.net","path":"/m2a","url":"http://localhost:8080","lets_encrypt":true, "strip_prefix": true}'
89-
```
75+
### Mobile App
9076

91-
Configure traefik to route /_matrix/push/v1/notify to the proxy:
92-
```
93-
api-cli run set-route --agent module/traefik1 --data '{"instance": "matrix1-push", "name":"synapse-push","host":"synapse.gs.nethserver.net","path":"/_matrix/push/v1/notify","url":"http://localhost:8080","lets_encrypt":true, "strip_prefix": false}'
94-
```
77+
To test the app, you must use the [NETHTEST](https://providers.cloudsoftphone.com/record/detail/15482) version.
9578

96-
Now:
97-
- login to Element with the first user (giacomo)
98-
- login to Element with the second user (mario)
99-
100-
After the above logins, you can send a message from giacomo (91201) to mario (202) using the proxy API:
101-
```
102-
curl -s -X POST https://synapse.gs.nethserver.net/m2a/api/client/send_message -H "Content-Type: application/json" -d '{
103-
"from": "91201",
104-
"password": "giacomo",
105-
"to": "202",
106-
"body": "Hello Mario — this is Giacomo (curl test)",
107-
"content_type": "text/plain"
108-
}'
109-
```
110-
111-
Send message using Matrix ID as recipient - Giacomo to Mario:
112-
```
113-
curl -s -X POST https://synapse.gs.nethserver.net/m2a/api/client/send_message -H "Content-Type: application/json" -d '{
114-
"from": "91201",
115-
"password": "giacomo",
116-
"to": "@mario:synapse.gs.nethserver.net",
117-
"body": "Hello Mario — this is Giacomo (curl test)",
118-
"content_type": "text/plain"
119-
}'
120-
```
79+
1. Download the [Cloud Softphone](https://play.google.com/store/apps/details?id=cz.acrobits.softphone.cloudphone&hl=it) application.
80+
2. Log in with these credentials:
81+
* **Username:** `user1@<fqdn_nethvoice>@NETHTEST*`
82+
* **Password:** `<password_user1>`
83+
(If this login does not work, you need to create a dummy QR code on the NETHTEST app).
84+
3. Try sending a message to another user: the message should be delivered to the Matrix client, and replies should return to the app.
85+
4. Write a message from Cinny to the app (a room will open after step 3); the message should be delivered via push notification if the app is closed.
12186

0 commit comments

Comments
 (0)