Skip to content

Commit 120daea

Browse files
sidey79sidey79
committed
docs: Add docs and env variables support
1 parent 2996d97 commit 120daea

3 files changed

Lines changed: 158 additions & 0 deletions

File tree

‎.devcontainer/.devcontainer.env.sample‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,40 @@
1+
# MQTT Broker Konfiguration
2+
# Die Adresse des MQTT Brokers (z.B. Mosquitto).
3+
MQTT_HOST=localhost
4+
5+
# Der Port des MQTT Brokers (Standard: 1883).
6+
MQTT_PORT=1883
7+
8+
# Der Benutzername für die Authentifizierung am MQTT Broker.
9+
# Optional: Leer lassen, wenn keine Authentifizierung erforderlich ist.
10+
MQTT_USERNAME=
11+
12+
# Das Passwort für die Authentifizierung am MQTT Broker.
13+
# Optional: Leer lassen, wenn keine Authentifizierung erforderlich ist.
14+
MQTT_PASSWORD=
15+
16+
# Das Basis-Topic für Signalduino Nachrichten.
17+
# Nachrichten werden unter $MQTT_TOPIC/<protokoll_id> veröffentlicht.
18+
# Befehle werden unter $MQTT_TOPIC/commands/# erwartet.
19+
MQTT_TOPIC=signalduino/messages
20+
21+
# Signalduino Verbindungseinstellungen (für direkte Verwendung in main.py)
22+
# Wähle entweder eine serielle Verbindung ODER eine TCP-Verbindung.
23+
24+
# Serieller Port für die Verbindung zum Signalduino (z.B. /dev/ttyUSB0).
25+
# Wird verwendet, wenn das Skript mit --serial gestartet wird oder um Standardwerte zu setzen.
26+
SIGNALDUINO_SERIAL_PORT=/dev/ttyUSB0
27+
28+
# Baudrate für die serielle Verbindung (Standard: 57600).
29+
SIGNALDUINO_BAUD=57600
30+
31+
# TCP Host für die Verbindung zum Signalduino über Netzwerk (z.B. ESP-Link).
32+
# Wird verwendet, wenn das Skript mit --tcp gestartet wird.
33+
SIGNALDUINO_TCP_HOST=192.168.1.10
34+
35+
# TCP Port für die Verbindung zum Signalduino (Standard: 23).
36+
SIGNALDUINO_TCP_PORT=23
37+
38+
# Logging Level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
39+
# Steuert die Ausführlichkeit der Log-Ausgaben.
40+
LOG_LEVEL=INFO

‎.devcontainer/devcontainer.json‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
// For format details, see https://aka.ms/devcontainer.json. For config options, see the
2+
// README at: https://github.com/devcontainers/templates/tree/main/src/python
3+
{
4+
"name": "Python 3",
5+
// Or use a Dockerfile or Docker Compose file. More info: https://containers.dev/guide/dockerfile
6+
"image": "mcr.microsoft.com/devcontainers/python:2-3-bookworm",
7+
"features": {
8+
//"ghcr.io/hspaans/devcontainer-features/pytest:2": {}
9+
},
10+
11+
// Features to add to the dev container. More info: https://containers.dev/features.
12+
// "features": {},
13+
14+
// Use 'forwardPorts' to make a list of ports inside the container available locally.
15+
// "forwardPorts": [],
16+
17+
// Use 'postCreateCommand' to run commands after the container is created.
18+
"postCreateCommand": "pip3 install --user -r requirements-dev.txt || exit 0",
19+
"customizations": {
20+
"vscode": {
21+
"extensions": [
22+
"RooVeterinaryInc.roo-cline"
23+
]
24+
}
25+
},
26+
"runArgs": ["--env-file", ".devcontainer/devcontainer.env"]
27+
28+
// Configure tool-specific properties.
29+
// "customizations": {},
30+
31+
// Uncomment to connect as root instead. More info: https://aka.ms/dev-containers-non-root.
32+
// "remoteUser": "root"
33+
}

‎docs/devcontainer_env.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# Verwenden von Umgebungsvariablen in Dev Containern (`.devcontainer.env`)
2+
3+
Dieses Dokument beschreibt die Verwendung einer dedizierten Datei zur Bereitstellung von Umgebungsvariablen für Ihren Dev Container, um Geheimnisse und benutzerspezifische Einstellungen von der Versionskontrolle fernzuhalten.
4+
5+
## 1. Zweck
6+
7+
Die Datei dient dazu, **Umgebungsvariablen** (z. B. API-Tokens, geheime Schlüssel, benutzerspezifische Pfade oder Einstellungen) in den laufenden Development Container einzuspeisen. Dies ist ein wichtiger Mechanismus, um zu verhindern, dass sensible oder benutzerspezifische Daten in der Konfigurationsdatei [`devcontainer.json`](.devcontainer/devcontainer.json) hartcodiert oder versehentlich in das Git-Repository committet werden.
8+
9+
## 2. Erstellung und Speicherort
10+
11+
1. **Speicherort:** Erstellen Sie die Datei manuell. Es wird empfohlen, sie im Ordner [`./.devcontainer`](.devcontainer/) zu speichern, z.B. als [`./.devcontainer/.devcontainer.env`](.devcontainer/.devcontainer.env).
12+
2. **Versionskontrolle:** **Wichtig:** Fügen Sie den Dateinamen (z.B. `.devcontainer/.devcontainer.env`) sofort der Datei [`./.gitignore`](.gitignore) hinzu, um zu verhindern, dass die Umgebungsvariablen versehentlich in das Git-Repository committet werden.
13+
14+
## 3. Format
15+
16+
Die Datei ist eine einfache Textdatei und folgt den Standard-`.env`-Dateikonventionen:
17+
18+
* Jede Zeile enthält ein Schlüssel-Wert-Paar.
19+
* Das Format ist `SCHLÜSSEL=WERT`.
20+
* Kommentare beginnen mit `#`.
21+
22+
```
23+
# Beispiel für .devcontainer.env
24+
API_KEY=mein_geheimer_schluessel_12345
25+
USER_EMAIL=ich@beispiel.de
26+
LOG_LEVEL=DEBUG
27+
```
28+
29+
## 4. Verwendung mit Dockerfile/Image-basierten Dev Containern
30+
31+
Wenn Sie eine Konfiguration verwenden, die direkt auf einem Dockerfile oder einem Docker-Image basiert (erkennbar an der Verwendung von `"dockerfile"` oder `"image"` in [`devcontainer.json`](.devcontainer/devcontainer.json)), verwenden Sie das Docker CLI-Argument `--env-file` in der Eigenschaft `"runArgs"`:
32+
33+
```json
34+
// .devcontainer/devcontainer.json
35+
{
36+
// ...
37+
"runArgs": [
38+
"--env-file",
39+
"./.devcontainer.env" // Pfad relativ zum .devcontainer-Ordner
40+
]
41+
// ...
42+
}
43+
```
44+
45+
## 5. Verwendung mit Docker Compose-basierten Dev Containern
46+
47+
Wenn Sie eine Konfiguration verwenden, die auf Docker Compose basiert (erkennbar an der Verwendung von `"dockerComposeFile"` in [`devcontainer.json`](.devcontainer/devcontainer.json)), fügen Sie den Schlüssel `env_file` zum entsprechenden Service in Ihrer [`docker-compose.yml`](docker-compose.yml) hinzu:
48+
49+
```yaml
50+
# docker-compose.yml
51+
version: '3.8'
52+
services:
53+
app:
54+
build: .
55+
# ... andere Konfigurationen ...
56+
env_file:
57+
- ./.devcontainer/.devcontainer.env # Pfad relativ zur docker-compose.yml
58+
```
59+
60+
## 6. Best Practice: Beispiel-Datei
61+
62+
Um anderen Entwicklern mitzuteilen, welche Umgebungsvariablen benötigt werden, existiert eine **Beispiel-Datei**:
63+
64+
* **Name:** [`./.devcontainer/.devcontainer.env.sample`](.devcontainer/.devcontainer.env.sample) (oder ähnlich).
65+
* **Inhalt:** Führen Sie die benötigten Variablen mit leeren oder Platzhalter-Werten auf.
66+
67+
```
68+
# .devcontainer/.devcontainer.env.sample
69+
# Kopieren Sie diese Datei nach .devcontainer/.devcontainer.env und füllen Sie die Werte aus.
70+
71+
# MQTT Broker Konfiguration
72+
MQTT_HOST=localhost
73+
MQTT_PORT=1883
74+
MQTT_USERNAME=
75+
MQTT_PASSWORD=
76+
MQTT_TOPIC=signalduino/messages
77+
78+
# Signalduino Verbindungseinstellungen
79+
SIGNALDUINO_SERIAL_PORT=/dev/ttyUSB0
80+
SIGNALDUINO_BAUD=57600
81+
# SIGNALDUINO_TCP_HOST=192.168.1.10
82+
# SIGNALDUINO_TCP_PORT=23
83+
84+
# Logging
85+
LOG_LEVEL=INFO

0 commit comments

Comments
 (0)