Skip to content

Commit 7053375

Browse files
KoenigMjrKoenigMjr
committed
feat: Interaktives Installationsskript mit Mehrsprachigkeit, argparse und Logging
- Neues CLI-Interface via argparse für flexible Steuerung - Unterstützt Dry-Run-Modus zur sicheren Vorschau - Sprachumschaltung via --lang (de/en) - Internationalisierung aller Ausgaben via `t()` und `TEXT`-Dict (Deutsch/Englisch) - Logging mit farbiger Terminalausgabe und Logdatei (log/install/) - YAML-Validierung und Service-Typ-Erkennung (client/server) - Interaktive Benutzerführung für (De)Installation von Services - Verbesserte Fehlerbehandlung und Nutzerabfragen mit Fallback - DOKU: - Install.md (Installation von BW3) ergänzt - Service.md (für Install as a Service-Skript) zweisprachig (Deutsch/Englisch) ergänzt - mkdocs um Seiten Install/Service/Usage.md ergänzt
1 parent 5d9ab0a commit 7053375

5 files changed

Lines changed: 839 additions & 3 deletions

File tree

‎docu/docs/install.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
# 🇩🇪 Anleitung zur Installation von BOSWatch3
2+
Die Installation von BOSWatch3 wird mittels diesem bash-Skript weitestgehend automatisiert durchgeführt.
3+
## 1. Installationsskript herunterladen
4+
Zunächst wird das aktuelle Installationsskript heruntergeladen
5+
Öffne ein Terminal und führe folgenden Befehl aus:
6+
7+
```bash
8+
wget https://github.com/BOSWatch/BW3-Core/raw/master/install.sh
9+
```
10+
11+
## 2. Installationsskript ausführen
12+
Im Anschluss wird das Skript mit dem Kommando
13+
14+
```bash
15+
sudo bash install.sh
16+
```
17+
18+
ausgeführt.
19+
20+
### 2a. Optionale Parameter beim Installieren
21+
Standardmäßig wird das Programm nach /opt/boswatch3 installiert. Folgende Parameter stehen zur Installation zur Verfügung:
22+
23+
| Parameter | Zulässige Werte | Beschreibung |
24+
| ---------------- | ----------------------- | --------------------------------------------------------------------------------------------------- |
25+
| `-r`, `--reboot` | *(kein Wert notwendig)* | Führt nach der Installation automatisch einen Neustart durch. Ohne Angabe erfolgt **kein** Reboot. |
26+
| `-b`, `--branch` | `master`, `develop` | Wählt den zu installierenden Branch. `master` ist stabil (empfohlen), `develop` ist für Entwickler. |
27+
| `-p`, `--path` | z. B. `/opt/boswatch3` | Installiert BOSWatch3 in ein anderes Verzeichnis (**nicht empfohlen**). Standard ist `/opt/boswatch3`. |
28+
29+
**ACHTUNG:**
30+
Eine Installation von BOSWatch3 in ein anderes Verzeichnis erfordert viele Anpassungen in den Skripten und erhöht das Risiko, dass das Programm zu Fehlern führt. Es wird dazu geraten, das Standardverzeichnis zu benutzen.
31+
32+
Falls eine Installation mit Parameter gewünscht wird, so kann dies wie in folgendem Beispiel gestartet werden:
33+
34+
```bash
35+
sudo bash install.sh --branch master --path /opt/boswatch3 --reboot
36+
```
37+
38+
## 3. Konfiguration nach der Installation
39+
Nach der Installation muss die Konfiguration der Dateien `/opt/boswatch3/config/client.yaml`
40+
und `/opt/boswatch3/config/server.yaml` angepasst werden (z.B. mit nano, WinSCP,...):
41+
42+
```bash
43+
sudo nano /opt/boswatch3/config/client.yaml
44+
```
45+
46+
und
47+
48+
```bash
49+
sudo nano /opt/boswatch3/config/server.yaml
50+
```
51+
52+
Passe die Einstellungen nach deinen Anforderungen an. Bei einem Upgrade einer bestehenden Version kann dieser Schritt ggf. entfallen.
53+
54+
**INFORMATION:**
55+
Weitere Informationen zur Konfiguration:
56+
[Konfiguration](/docu/docs/config.md)
57+
58+
## 4. Neustart
59+
**WICHTIG:**
60+
Bitte starte das System neu, bevor du BOSWatch3 zum ersten Mal startest!
61+
62+
```bash
63+
sudo reboot
64+
```
65+
66+
## 5. Start von BOSWatch3
67+
weiter gehts bei [BOSWatch benutzen](usage.md)
68+
69+
---
70+
71+
# 🇬🇧 BOSWatch3 Installation Guide
72+
The installation of BOSWatch3 is largely automated using this bash script.
73+
74+
## 1. Download the Installation Script
75+
First, download the latest installation script.
76+
Open a terminal and run the following command:
77+
78+
```bash
79+
wget https://github.com/BOSWatch/BW3-Core/raw/master/install.sh
80+
```
81+
82+
## 2. Run the Installation Script
83+
Then run the script with the command:
84+
85+
```bash
86+
sudo bash install.sh
87+
```
88+
89+
### 2a. Optional Parameters for Installation
90+
By default, the program is installed to `/opt/boswatch3`. The following parameters are available for installation:
91+
92+
| Parameter | Allowed Values | Description |
93+
| ---------------- | -----------------------| --------------------------------------------------------------------------------------------------- |
94+
| `-r`, `--reboot` | *(no value needed)* | Automatically reboots the system after installation. Without this, **no** reboot will be performed. |
95+
| `-b`, `--branch` | `master`, `develop` | Selects the branch to install. `master` is stable (recommended), `develop` is for developers. |
96+
| `-p`, `--path` | e.g. `/opt/boswatch3` | Installs BOSWatch3 to a different directory (**not recommended**). Default is `/opt/boswatch3`. |
97+
98+
**WARNING:**
99+
Installing BOSWatch3 to a different directory requires many adjustments in the scripts and increases the risk of errors. It is recommended to use the default directory.
100+
101+
If you want to install with parameters, you can run the following example command:
102+
103+
```bash
104+
sudo bash install.sh --branch master --path /opt/boswatch3 --reboot
105+
```
106+
107+
## 3. Configuration After Installation
108+
After installation, the configuration files `/opt/boswatch3/config/client.yaml`
109+
and `/opt/boswatch3/config/server.yaml` must be adjusted (e.g. using nano, WinSCP, ...):
110+
111+
```bash
112+
sudo nano /opt/boswatch3/config/client.yaml
113+
```
114+
115+
and
116+
117+
```bash
118+
sudo nano /opt/boswatch3/config/server.yaml
119+
```
120+
121+
Adjust the settings according to your requirements. If upgrading from an existing version, this step might be skipped.
122+
123+
**INFORMATION:**
124+
More information about configuration:
125+
[Configuration](/docu/docs/config.md)
126+
127+
## 4. Reboot
128+
**IMPORTANT:**
129+
Please reboot the system before starting BOSWatch3 for the first time!
130+
131+
```bash
132+
sudo reboot
133+
```
134+
135+
## 5. Starting BOSWatch3
136+
Continue with [Using BOSWatch](usage.md)

‎docu/docs/service.md‎

Lines changed: 166 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,166 @@
1+
# BOSWatch – Dienstinstallation (Service Setup)
2+
3+
## 🇩🇪 BOSWatch als Dienst verwenden
4+
Es wird vorausgesetzt, dass BOSWatch unter `/opt/boswatch3` installiert ist.
5+
Falls du einen anderen Installationspfad nutzt, müssen alle Pfadangaben in dieser Anleitung, im Skript sowie in den generierten Service-Dateien entsprechend angepasst werden.
6+
7+
Für jeden Dienst muss eine eigene `*.yaml`-Datei im Ordner `config/` vorhanden sein.
8+
Beim Ausführen des Skripts wirst du interaktiv gefragt, welche dieser YAML-Dateien installiert oder übersprungen werden sollen.
9+
10+
### Dienst installieren
11+
Als Erstes wechseln wir ins BOSWatch Verzeichnis:
12+
13+
```bash
14+
cd /opt/boswatch3
15+
```
16+
17+
Das Installationsskript `install_service.py` wird anschließend mit Root-Rechten ausgeführt:
18+
```bash
19+
sudo python3 install_service.py
20+
```
21+
Es folgt ein interaktiver Ablauf, bei dem du gefragt wirst, welche YAML-Dateien installiert oder entfernt werden sollen.
22+
23+
### Zusätzliche Optionen (fortgeschrittene Anwender)
24+
Das Skript bietet zusätzliche CLI-Optionen für mehr Kontrolle:
25+
26+
```bash
27+
usage: install_service.py [-h] [--verbose] [--quiet]
28+
29+
Installiert oder entfernt systemd-Services für BOSWatch basierend auf YAML-Konfigurationsdateien.
30+
31+
optional arguments:
32+
-h, --help zeigt diese Hilfe an
33+
--dry-run für Entwickler: führt keine echten Änderungen aus (Simulation)
34+
--verbose zeigt ausführliche Debug-Ausgaben
35+
--quiet unterdrückt alle Ausgaben außer Warnungen und Fehlern
36+
-l, --lang [de|en] Sprache für alle Ausgaben (Standard: de)
37+
```
38+
39+
### Neustart nach Serviceinstallation
40+
Nach Durchlaufen des Skripts boote dein System erneut durch, um den korrekten Startvorgang zu überprüfen:
41+
```bash
42+
sudo reboot
43+
```
44+
45+
### Kontrolle, ob alles funktioniert hat
46+
Um zu kontrollieren, ob alles ordnungsgemäß hochgefahren ist, kannst du die zwei Services mit folgenden Befehlen abfragen und die letzten Log-Einträge ansehen:
47+
48+
1. Client-Service
49+
```bash
50+
sudo systemctl status bw3_[clientname].service
51+
```
52+
53+
Ersetze [clientname] mit dem Namen, den deine client.yaml hat (Standardmäßig: client)
54+
55+
Um das Log zu schließen, "q" drücken.
56+
57+
2. Server-Service
58+
```bash
59+
sudo systemctl status bw3_[servername].service
60+
```
61+
62+
Ersetze [servername] mit dem Namen, den deine server.yaml hat (Standardmäßig: server)
63+
64+
Um das Log zu schließen, "q" drücken.
65+
66+
**Beide Outputs sollten so ähnlich beginnen:**
67+
```text
68+
bw3_client.service - BOSWatch Client
69+
Loaded: loaded (/etc/systemd/system/bw3_client.service; enabled; preset: enabled)
70+
Active: active (running) since Mon 1971-01-01 01:01:01 CEST; 15min 53s ago
71+
```
72+
73+
Falls du in deinen letzten Logzeilen keine Error vorfinden kannst, die auf einen Stopp des Clients bzw. Server hinweisen, läuft das Programm wie gewünscht, sobald du deinen Rechner startest.
74+
75+
### Logdatei
76+
Alle Aktionen des Installationsskripts werden in der Datei log/install/service_install.log protokolliert.
77+
78+
### Hinweis
79+
Nach der Installation oder Entfernung wird systemctl daemon-reexec automatisch aufgerufen, damit systemd die neuen oder entfernten Units korrekt verarbeitet.
80+
81+
---
82+
83+
## 🇬🇧 Use BOSWatch as a Service
84+
85+
We assume that BOSWatch is installed to `/opt/boswatch3`.
86+
If you are using a different path, please adjust all paths in this guide, in the script and in the generated service files accordingly.
87+
88+
Each service requires its own `*.yaml` file inside the `config/` folder.
89+
The script will interactively ask which YAML files to install or skip.
90+
91+
### Install the Service
92+
93+
First, change directory to BOSWatch folder:
94+
95+
```bash
96+
cd /opt/boswatch3
97+
```
98+
99+
After that, run the install script `install_service.py` with root permissions:
100+
101+
```bash
102+
sudo python3 install_service.py -l en
103+
```
104+
105+
You will be guided through an interactive selection to install or remove desired services.
106+
107+
### Additional Options
108+
109+
The script supports additional CLI arguments for advanced usage:
110+
111+
```bash
112+
usage: install_service.py [-h] [--dry-run] [--verbose] [--quiet]
113+
114+
Installs or removes BOSWatch systemd services based on YAML config files.
115+
116+
optional arguments:
117+
-h, --help show this help message and exit
118+
--dry-run simulate actions without making real changes
119+
--verbose show detailed debug output
120+
--quiet suppress all output except warnings and errors
121+
-l, --lang [de|en] Language for all output (default: de)
122+
```
123+
124+
### Reboot After Setup
125+
After running the script, reboot your system to verify that the services start correctly:
126+
```bash
127+
sudo reboot
128+
```
129+
130+
### Verifying Successful Setup
131+
To check if everything started properly, you can query the two services and inspect the most recent log entries:
132+
133+
1. Client Service
134+
```bash
135+
sudo systemctl status bw3_[clientname].service
136+
```
137+
138+
Replace [clientname] with the name of your client.yaml file (default: client).
139+
140+
To close the log, press "q".
141+
142+
2. Server Service
143+
```bash
144+
sudo systemctl status bw3_[servername].service
145+
```
146+
147+
Replace [servername] with the name of your server.yaml file (default: server).
148+
149+
To close the log, press "q".
150+
151+
**Both outputs should start similarly to this:**
152+
```text
153+
bw3_client.service - BOSWatch Client
154+
Loaded: loaded (/etc/systemd/system/bw3_client.service; enabled; preset: enabled)
155+
Active: active (running) since Mon 1971-01-01 01:01:01 CEST; 15min 53s ago
156+
```
157+
158+
If the latest log entries do not show any errors indicating a client or server crash, then the services are running correctly and will automatically start on boot.
159+
160+
### Log File
161+
162+
All actions of the installation script are logged to `log/install/service_install.log`.
163+
164+
### Note
165+
166+
After installation or removal, `systemctl daemon-reexec` is automatically triggered to reload unit files properly.

‎docu/docs/usage.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
# 🇩🇪 Start von BOSWatch3
2+
Nach dem Neustart kannst du BOSWatch3 wie folgt starten:
3+
4+
```bash
5+
cd /opt/boswatch3
6+
sudo python3 bw_client.py -c config/client.yaml
7+
sudo python3 bw_server.py -c config/server.yaml
8+
```
9+
10+
## Optional: Als Dienst einrichten
11+
Weiter gehts mit [als Service einrichten](service.md)
12+
13+
---
14+
15+
# 🇬🇧 Starting BOSWatch3
16+
After reboot, you can start BOSWatch3 as follows:
17+
18+
```bash
19+
cd /opt/boswatch3
20+
sudo python3 bw_client.py -c config/client.yaml
21+
sudo python3 bw_server.py -c config/server.yaml
22+
```
23+
24+
## Optional: Setup as a Service
25+
For further instructions, see [Setup as a Service](service.md)

‎docu/mkdocs.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,10 @@ edit_uri: edit/develop/docu/docs/
77
nav:
88
# - BW3: index.md
99
- Quick Start:
10-
- Installation: tbd.md
10+
- Installation: install.md
1111
- Konfiguration: config.md
12-
# - BOSWatch benutzen: tbd.md
13-
# - Als Service einrichten: tbd.md
12+
- BOSWatch benutzen: usage.md
13+
- Als Service einrichten: service.md
1414
- Informationen:
1515
- Server/Client Prinzip: information/serverclient.md
1616
- Broadcast Service: information/broadcast.md

0 commit comments

Comments
 (0)