Skip to content

Commit a40f980

Browse files
kemboi22kemboi22
committed
feat: updated README
1 parent c7b06f9 commit a40f980

1 file changed

Lines changed: 64 additions & 75 deletions

File tree

‎README.md‎

Lines changed: 64 additions & 75 deletions
Original file line numberDiff line numberDiff line change
@@ -1,125 +1,114 @@
11
# ns8-matomo
22

3-
This is a module for [ns8-matomo8] for the Project (https://github.com/matomo-org/matomo).
4-
This is a module is based on the matomo Docker [matomo.org] (https://github.com/matomo-org/docker).
3+
This is a module for [NS8](https://github.com/NethServer/ns8-matomo) for the [Matomo](https://github.com/matomo-org/matomo) project.
54

6-
Start and configure a Matomo instance:
5+
The module is based on the official [Matomo Docker image](https://github.com/matomo-org/docker).
76

8-
with PHP FPM + nginx as a proxy
9-
redis caching
10-
MariaDB database The module uses Official matomo image.
7+
## Features
118

12-
1. Rename some references inside the repo:
13-
```
14-
modulename=$(basename $(pwd) | sed 's/^ns8-//')
15-
git mv imageroot/systemd/user/matomo.service imageroot/systemd/user/${modulename}.service
16-
git mv tests/matomo.robot tests/${modulename}.robot
17-
sed -i "s/matomo/${modulename}/g" $(find .github/ * -type f)
18-
git commit -a -m "Repository initialization"
19-
```
20-
21-
22-
23-
1. Adjust `.github/workflows` to your needs. `clean-registry.yml` might
24-
need the proper list of image names to work correctly. Unused workflows
25-
can be disabled from the GitHub Actions interface.
26-
27-
1. Commit and push your local changes
9+
- PHP FPM with nginx as reverse proxy
10+
- Redis caching
11+
- MariaDB database
2812

2913
## Install
3014

3115
Instantiate the module with:
3216

33-
add-module ghcr.io/compgeniuses/matomo:latest 1
17+
```bash
18+
add-module ghcr.io/geniusdynamics/matomo:latest 1
19+
```
3420

3521
The output of the command will return the instance name.
36-
Output example:
3722

38-
{"module_id": "matomo1", "image_name": "matomo", "image_url": "ghcr.io/compgeniuses/matomo:latest"}
23+
Example output:
24+
25+
```json
26+
{"module_id": "matomo1", "image_name": "matomo", "image_url": "ghcr.io/geniusdynamics/matomo:latest"}
27+
```
3928

4029
## Configure
4130

42-
Let's assume that the dokuwiki istance is named `matomo1`.
31+
Assuming the Matomo instance is named `matomo1`, launch `configure-module` with the following parameters:
32+
33+
### MariaDB Service Configuration
4334

44-
Then launch `configure-module`, by setting the following parameters:
45-
## MAriDB Service Configurations
35+
| Parameter | Value |
36+
|-----------|-------|
37+
| `MYSQL_ROOT_PASSWORD` | Set a strong password for root user |
38+
| `MARIADB_AUTO_UPGRADE` | 1 |
39+
| `MARIADB_DISABLE_UPGRADE_BACKUP` | 1 |
4640

47-
- `MYSQL_ROOT_PASSWORD`:
48-
- `MARIADB_AUTO_UPGRADE`: 1
49-
- `MARIADB_DISABLE_UPGRADE_BACKUP`: 1
41+
### Database Configuration
5042

51-
## DB Configurations
43+
| Parameter | Description |
44+
|-----------|-------------|
45+
| `MYSQL_PASSWORD` | Password for the Matomo database user |
46+
| `MYSQL_DATABASE` | Name of the Matomo database |
47+
| `MYSQL_USER` | Username for the Matomo database |
48+
| `MATOMO_DATABASE_ADAPTER` | mysql |
49+
| `MATOMO_DATABASE_TABLES_PREFIX` | Table prefix (optional) |
50+
| `MATOMO_DATABASE_USERNAME` | Database username |
51+
| `MATOMO_DATABASE_PASSWORD` | Database password |
52+
| `MATOMO_DATABASE_DBNAME` | Database name |
53+
| `MARIADB_INITDB_SKIP_TZINFO` | 1 |
5254

53-
- `MYSQL_PASSWORD`: administrator mail address
54-
- `MYSQL_DATABASE`: administrator mail address
55-
- `MYSQL_USER`: administrator mail address
56-
- `MATOMO_DATABASE_ADAPTER`: mysql
57-
- `MATOMO_DATABASE_TABLES_PREFIX`: administrator mail address
58-
- `MATOMO_DATABASE_USERNAME`: administrator mail address
59-
- `MATOMO_DATABASE_PASSWORD`: administrator mail address
60-
- `MATOMO_DATABASE_DBNAME`: administrator mail address
61-
- `MARIADB_AUTO_UPGRADE`: 1
62-
- `MARIADB_INITDB_SKIP_TZINFO`: 1
55+
### Matomo Environment Configuration
6356

64-
## matomo env Configurations
65-
- `MATOMO_DATABASE_HOST`: 1
66-
- `PHP_MEMORY_LIMIT`: 2048
67-
- `host`: a fully qualified domain name for the wiki
68-
- `http2https`: enable or disable HTTP to HTTPS redirection
69-
- `lets_encrypt`: enable or disable Let's Encrypt certificate
57+
| Parameter | Description |
58+
|-----------|-------------|
59+
| `MATOMO_DATABASE_HOST` | Database host (e.g., MariaDB module) |
60+
| `PHP_MEMORY_LIMIT` | PHP memory limit (e.g., 2048M) |
61+
| `host` | Fully qualified domain name for Matomo |
62+
| `http2https` | Enable or disable HTTP to HTTPS redirection |
63+
| `lets_encrypt` | Enable or disable Let's Encrypt certificate |
7064

7165
Example:
7266

73-
api-cli run module/matomo1/configure-module --data '{}'
67+
```bash
68+
api-cli run module/matomo1/configure-module --data '{}'
69+
```
7470

75-
The above command will:
76-
- start and configure the matomo instance
77-
- (describe configuration process)
78-
- ...
71+
The above command will start and configure the Matomo instance.
7972

80-
Send a test HTTP request to the matomo backend service:
73+
Test the Matomo backend service:
8174

82-
curl http://127.0.0.1/matomo/
75+
```bash
76+
curl http://127.0.0.1/matomo/
77+
```
8378

84-
## Smarthost setting discovery
79+
## Smarthost Setting Discovery
8580

86-
Some configuration settings, like the smarthost setup, are not part of the
87-
`configure-module` action input: they are discovered by looking at some
88-
Redis keys. To ensure the module is always up-to-date with the
89-
centralized [smarthost
90-
setup](https://compgeniuses.github.io/ns8-core/core/smarthost/) every time
91-
matomo starts, the command `bin/discover-smarthost` runs and refreshes
92-
the `state/smarthost.env` file with fresh values from Redis.
81+
Some configuration settings, like the smarthost setup, are not part of the `configure-module` action input: they are discovered by looking at some Redis keys. To ensure the module is always up-to-date with the centralized [smarthost setup](https://geniusdynamics.github.io/ns8-core/core/smarthost/) every time Matomo starts, the command `bin/discover-smarthost` runs and refreshes the `state/smarthost.env` file with fresh values from Redis.
9382

94-
Furthermore if smarthost setup is changed when matomo is already
95-
running, the event handler `events/smarthost-changed/10reload_services`
96-
restarts the main module service.
83+
Furthermore if smarthost setup is changed when Matomo is already running, the event handler `events/smarthost-changed/10reload_services` restarts the main module service.
9784

9885
See also the `systemd/user/matomo.service` file.
9986

100-
This setting discovery is just an example to understand how the module is
101-
expected to work: it can be rewritten or discarded completely.
87+
This setting discovery is just an example to understand how the module is expected to work: it can be rewritten or discarded completely.
10288

10389
## Uninstall
10490

10591
To uninstall the instance:
10692

107-
remove-module --no-preserve matomo1
93+
```bash
94+
remove-module --no-preserve matomo1
95+
```
10896

10997
## Testing
11098

11199
Test the module using the `test-module.sh` script:
112100

101+
```bash
102+
./test-module.sh <NODE_ADDR> ghcr.io/geniusdynamics/matomo:latest
103+
```
113104

114-
./test-module.sh <NODE_ADDR> ghcr.io/compgeniuses/matomo:latest
115-
116-
The tests are made using [Robot Framework](https://robotframework.org/)
105+
The tests are made using [Robot Framework](https://robotframework.org/).
117106

118-
## UI translation
107+
## UI Translation
119108

120109
Translated with [Weblate](https://hosted.weblate.org/projects/ns8/).
121110

122111
To setup the translation process:
123112

124-
- add [GitHub Weblate app](https://docs.weblate.org/en/latest/admin/continuous.html#github-setup) to your repository
125-
- add your repository to [hosted.weblate.org]((https://hosted.weblate.org) or ask a compgeniuses developer to add it to ns8 Weblate project
113+
1. Add [GitHub Weblate app](https://docs.weblate.org/en/latest/admin/continuous.html#github-setup) to your repository
114+
2. Add your repository to [hosted.weblate.org](https://hosted.weblate.org) or ask a NethServer developer to add it to the NS8 Weblate project

0 commit comments

Comments
 (0)