Skip to content

Commit fe93015

Browse files
compgeniusescompgeniuses
committed
Update ReadMe
1 parent e312b7a commit fe93015

1 file changed

Lines changed: 98 additions & 90 deletions

File tree

‎README.md‎

Lines changed: 98 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -1,33 +1,34 @@
11
# ns8-semaphoreui
22

3-
This is a template module for [NethServer 8](https://github.com/NethServer/ns8-core).
4-
To start a new module from it:
3+
This is a module for [NethServer 8](https://github.com/NethServer/ns8-core) that installs [Semaphore](https://github.com/ansible-semaphore/semaphore), a modern open-source Ansible UI.
54

5+
---
66

7-
## Install
7+
## ✅ Install
88

99
Instantiate the module with:
1010

11-
add-module ghcr.io/geniusdynamics/semaphoreui:latest 1
12-
13-
The output of the command will return the instance name.
14-
Output example:
15-
16-
{"module_id": "semaphoreui1", "image_name": "semaphoreui", "image_url": "ghcr.io/geniusdynamics/semaphoreui:latest"}
11+
```bash
12+
add-module ghcr.io/geniusdynamics/semaphoreui:latest 1
13+
```
1714

18-
## Configure
15+
Example output:
1916

20-
Let's assume that the mattermost instance is named `semaphoreui1`.
17+
```json
18+
{
19+
"module_id": "semaphoreui1",
20+
"image_name": "semaphoreui",
21+
"image_url": "ghcr.io/geniusdynamics/semaphoreui:latest"
22+
}
23+
```
2124

22-
Launch `configure-module`, by setting the following parameters:
23-
- `host`: a fully qualified domain name for the application
24-
- `http2https`: enable or disable HTTP to HTTPS redirection (true/false)
25-
- `lets_encrypt`: enable or disable Let's Encrypt certificate (true/false)
25+
---
2626

27+
## ⚙️ Configure
2728

28-
Example:
29+
Assuming your instance is named `semaphoreui1`, configure it by setting the domain and HTTPS options:
2930

30-
```
31+
```bash
3132
api-cli run configure-module --agent module/semaphoreui1 --data - <<EOF
3233
{
3334
"host": "semaphoreui.domain.com",
@@ -37,110 +38,117 @@ api-cli run configure-module --agent module/semaphoreui1 --data - <<EOF
3738
EOF
3839
```
3940

40-
The above command will:
41-
- start and configure the semaphoreui instance
42-
- configure a virtual host for trafik to access the instance
41+
This command:
4342

44-
## Get the configuration
45-
You can retrieve the configuration with
43+
* Starts the Semaphore UI
44+
* Creates a virtual host via Traefik
4645

47-
```
48-
api-cli run get-configuration --agent module/semaphoreui1
49-
```
46+
---
5047

51-
## Uninstall
48+
## 📤 Email Configuration via SmartHost
5249

53-
To uninstall the instance:
50+
Email/SMTP settings are automatically discovered from the centralized SmartHost Redis configuration using the `discover-smarthost` hook.
5451

55-
remove-module --no-preserve semaphoreui1
52+
### Automatically injected values:
5653

57-
## Smarthost setting discovery
54+
* `SEMAPHORE_EMAIL_SENDER`
55+
* `SEMAPHORE_EMAIL_HOST`
56+
* `SEMAPHORE_EMAIL_PORT`
57+
* `SEMAPHORE_EMAIL_USERNAME`
58+
* `SEMAPHORE_EMAIL_PASSWORD`
5859

59-
Some configuration settings, like the smarthost setup, are not part of the
60-
`configure-module` action input: they are discovered by looking at some
61-
Redis keys. To ensure the module is always up-to-date with the
62-
centralized [smarthost
63-
setup](https://geniusdynamics.github.io/ns8-core/core/smarthost/) every time
64-
semaphoreui starts, the command `bin/discover-smarthost` runs and refreshes
65-
the `state/smarthost.env` file with fresh values from Redis.
60+
You do not need to pass these manually — they're refreshed at container start and on SmartHost changes.
6661

67-
Furthermore if smarthost setup is changed when semaphoreui is already
68-
running, the event handler `events/smarthost-changed/10reload_services`
69-
restarts the main module service.
62+
---
7063

71-
See also the `systemd/user/semaphoreui.service` file.
64+
## 🔔 Alert Integrations (Gotify & Telegram)
7265

73-
This setting discovery is just an example to understand how the module is
74-
expected to work: it can be rewritten or discarded completely.
66+
Optional alert integrations can be added by including the following variables in your JSON configuration:
7567

76-
## Debug
68+
### Gotify Alerts
7769

78-
some CLI are needed to debug
70+
* `SEMAPHORE_GOTIFY_ALERT`: "True" or "False"
71+
* `SEMAPHORE_GOTIFY_URL`: Your Gotify server URL
72+
* `SEMAPHORE_GOTIFY_TOKEN`: Application token
7973

80-
- The module runs under an agent that initiate a lot of environment variables (in /home/semaphoreui1/.config/state), it could be nice to verify them
81-
on the root terminal
74+
### Telegram Alerts
8275

83-
`runagent -m semaphoreui1 env`
76+
* `SEMAPHORE_TELEGRAM_ALERT`: "True" or "False"
77+
* `SEMAPHORE_TELEGRAM_CHAT`: Telegram Chat ID
78+
* `SEMAPHORE_TELEGRAM_TOKEN`: Bot token
8479

85-
- you can become runagent for testing scripts and initiate all environment variables
86-
87-
`runagent -m semaphoreui1`
80+
All alert settings are written into `app.env` and used on container startup.
8881

89-
the path become :
90-
```
91-
echo $PATH
92-
/home/semaphoreui1/.config/bin:/usr/local/agent/pyenv/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/usr/
82+
---
83+
84+
## 🔍 Get the configuration
85+
86+
```bash
87+
api-cli run get-configuration --agent module/semaphoreui1
9388
```
9489

95-
- if you want to debug a container or see environment inside
96-
`runagent -m semaphoreui1`
97-
```
98-
podman ps
99-
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
100-
d292c6ff28e9 localhost/podman-pause:4.6.1-1702418000 9 minutes ago Up 9 minutes 127.0.0.1:20015->80/tcp 80b8de25945f-infra
101-
d8df02bf6f4a docker.io/library/mariadb:10.11.5 --character-set-s... 9 minutes ago Up 9 minutes 127.0.0.1:20015->80/tcp mariadb-app
102-
9e58e5bd676f docker.io/library/nginx:stable-alpine3.17 nginx -g daemon o... 9 minutes ago Up 9 minutes 127.0.0.1:20015->80/tcp semaphoreui-app
90+
---
91+
92+
## ❌ Uninstall
93+
94+
```bash
95+
remove-module --no-preserve semaphoreui1
10396
```
10497

105-
you can see what environment variable is inside the container
98+
---
99+
100+
## 📡 SmartHost setting discovery
101+
102+
At container startup, `bin/discover-smarthost` populates `state/smarthost.env` by querying Redis. When SmartHost settings change, the event handler `events/smarthost-changed/10reload_services` restarts the container automatically.
103+
104+
---
105+
106+
## 🔎 Debugging Tips
107+
108+
### Check environment variables:
109+
110+
```bash
111+
runagent -m semaphoreui1 env
106112
```
107-
podman exec semaphoreui-app env
108-
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin
109-
TERM=xterm
110-
PKG_RELEASE=1
111-
MARIADB_DB_HOST=127.0.0.1
112-
MARIADB_DB_NAME=semaphoreui
113-
MARIADB_IMAGE=docker.io/mariadb:10.11.5
114-
MARIADB_DB_TYPE=mysql
115-
container=podman
116-
NGINX_VERSION=1.24.0
117-
NJS_VERSION=0.7.12
118-
MARIADB_DB_USER=semaphoreui
119-
MARIADB_DB_PASSWORD=semaphoreui
120-
MARIADB_DB_PORT=3306
121-
HOME=/root
113+
114+
### Launch interactive shell as agent:
115+
116+
```bash
117+
runagent -m semaphoreui1
122118
```
123119

124-
you can run a shell inside the container
120+
### Inspect running containers:
125121

122+
```bash
123+
podman ps
126124
```
127-
podman exec -ti semaphoreui-app sh
128-
/ #
125+
126+
### Check inside the container:
127+
128+
```bash
129+
podman exec semaphoreui-app env
130+
podman exec -ti semaphoreui-app sh
129131
```
130-
## Testing
131132

132-
Test the module using the `test-module.sh` script:
133+
---
133134

135+
## 🔮 Testing
136+
137+
Test the module using the following script:
138+
139+
```bash
140+
./test-module.sh <NODE_ADDR> ghcr.io/geniusdynamics/semaphoreui:latest
141+
```
134142

135-
./test-module.sh <NODE_ADDR> ghcr.io/geniusdynamics/semaphoreui:latest
143+
Test logic uses [Robot Framework](https://robotframework.org).
136144

137-
The tests are made using [Robot Framework](https://robotframework.org/)
145+
---
138146

139-
## UI translation
147+
## 🌎 UI Translation
140148

141-
Translated with [Weblate](https://hosted.weblate.org/projects/ns8/).
149+
This module supports [Weblate](https://hosted.weblate.org/projects/ns8/) for localization.
142150

143-
To setup the translation process:
151+
To contribute:
144152

145-
- add [GitHub Weblate app](https://docs.weblate.org/en/latest/admin/continuous.html#github-setup) to your repository
146-
- add your repository to [hosted.weblate.org]((https://hosted.weblate.org) or ask a NethServer developer to add it to ns8 Weblate project
153+
1. Add [GitHub Weblate app](https://docs.weblate.org/en/latest/admin/continuous.html#github-setup) to your repo.
154+
2. Add the repository to [hosted.weblate.org](https://hosted.weblate.org) or ask a NethServer developer to include it.

0 commit comments

Comments
 (0)