Skip to content

Commit 370f66d

Browse files
l2xul2xu
authored
Merge pull request #86 from AWildLeon/UserInstallationGuide
Docs: Installation Tutorial.
2 parents 0a6399d + 10510cd commit 370f66d

File tree

7 files changed

+288
-5
lines changed

7 files changed

+288
-5
lines changed

‎.github/workflows/docker-image.yml‎

Lines changed: 18 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,16 @@ jobs:
4343
username: ${{ github.actor }}
4444
password: ${{ secrets.GITHUB_TOKEN }}
4545

46+
# Check if any version tags exist
47+
- name: Check for existing version tags
48+
id: check-tags
49+
run: |
50+
if git tag --list 'v*.*' | grep -q .; then
51+
echo "has_version_tags=true" >> $GITHUB_OUTPUT
52+
else
53+
echo "has_version_tags=false" >> $GITHUB_OUTPUT
54+
fi
55+
4656
# Extract metadata (tags, labels) for Docker
4757
# https://github.com/docker/metadata-action
4858
- name: Extract Docker metadata
@@ -51,8 +61,13 @@ jobs:
5161
with:
5262
images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
5363
tags: |
54-
type=raw,value=testing-${{ github.ref_name }}
55-
type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
64+
type=raw,value=testing-${{ github.ref_name }},enable=${{ !startsWith(github.ref, 'refs/tags/v') }}
65+
type=raw,value=testing-main,enable=${{ github.ref == 'refs/heads/main' }}
66+
type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' && steps.check-tags.outputs.has_version_tags == 'false' }}
67+
type=raw,value=${{ github.ref_name }},enable=${{ startsWith(github.ref, 'refs/tags/v') }}
68+
type=semver,pattern={{version}}
69+
type=semver,pattern={{major}}.{{minor}}
70+
type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/v') }}
5671
5772
# Build and push Docker image with Buildx (don't push on PR)
5873
# https://github.com/docker/build-push-action
@@ -66,5 +81,4 @@ jobs:
6681
labels: ${{ steps.meta.outputs.labels }}
6782
cache-from: type=gha
6883
cache-to: type=gha,mode=max
69-
platforms: linux/amd64,linux/arm64
70-
84+
platforms: linux/amd64,linux/arm64

‎README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,15 @@ You can run the app with docker compose:
4040

4141
http://localhost:3000
4242

43+
## Installation Guides
44+
45+
For detailed installation instructions on different platforms:
46+
47+
- [Windows Installation (DE)](docs/Windows-Installation-de.md)
48+
- [Linux Installation (DE)](docs/Linux-Installation-de.md)
49+
- [Windows Installation (EN)](docs/Windows-Installation-en.md)
50+
- [Linux Installation (EN)](docs/Linux-Installation-en.md)
51+
4352
## License
4453

4554
This project is licensed under the AGPL-3.0-only. See the [LICENSE](./LICENSE) file for details.

‎docker-compose/docker-compose.yaml‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,8 @@
11
services:
22
betterbahn:
3-
image: ghcr.io/l2xu/betterbahn:testing-main
3+
image: ghcr.io/l2xu/betterbahn:latest
44
restart: unless-stopped
5+
environment:
6+
- TZ=Europe/Berlin # Timezone, dont Remove or else There will be time issues with tickets.
57
ports:
68
- "3000:3000"

‎docs/Linux-Installation-de.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Linux-Installationsanleitung
2+
3+
Diese Anleitung hilft Ihnen, BetterBahn auf Linux mit Docker zu installieren und auszuführen. Wir erklären jeden Schritt im Detail, als ob Sie neu bei der Befehlszeile sind.
4+
5+
## Voraussetzungen
6+
7+
- Eine Linux-Distribution (Ubuntu, Fedora, etc.)
8+
- Docker auf Ihrem System installiert. Falls nicht, folgen Sie den Anweisungen unter [https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/) für Ihre Distribution.
9+
- Docker Compose (normalerweise mit Docker enthalten, oder separat installieren falls nötig).
10+
- Stellen Sie sicher, dass Docker läuft: Öffnen Sie ein Terminal und führen Sie `sudo systemctl start docker` aus (falls systemd verwendet wird).
11+
12+
## Installationsschritte
13+
14+
1. **Ein Terminal öffnen**:
15+
- Drücken Sie Strg+Alt+T (auf den meisten Linux-Distributionen), um ein Terminalfenster zu öffnen.
16+
- Falls das nicht funktioniert, suchen Sie nach "Terminal" in Ihrem Anwendungsmenü.
17+
18+
2. **Docker Compose-Datei herunterladen**:
19+
- Im Terminal geben Sie den folgenden Befehl ein und drücken Enter:
20+
```
21+
curl -o docker-compose.yaml https://raw.githubusercontent.com/AWildLeon/betterbahn/main/docker-compose/docker-compose.yaml
22+
```
23+
Dies lädt die Datei in Ihr aktuelles Verzeichnis herunter (normalerweise Ihr Home-Ordner).
24+
- Falls curl nicht installiert ist, können Sie es mit `sudo apt install curl` (auf Ubuntu/Debian) oder entsprechend für Ihre Distribution installieren.
25+
- Alternativ manuell herunterladen:
26+
- Öffnen Sie Ihren Webbrowser und gehen Sie zu [https://raw.githubusercontent.com/AWildLeon/betterbahn/main/docker-compose/docker-compose.yaml](https://raw.githubusercontent.com/AWildLeon/betterbahn/main/docker-compose/docker-compose.yaml).
27+
- Rechtsklicken Sie auf die Seite und wählen Sie "Link speichern unter...", um die Datei als `docker-compose.yaml` in einem leicht zu findenden Ordner zu speichern, z.B. Downloads oder Desktop.
28+
29+
3. **In den Ordner navigieren (falls manuell heruntergeladen)**:
30+
- Falls Sie die Datei in einen bestimmten Ordner heruntergeladen haben, müssen Sie in der Eingabeaufforderung dorthin gehen.
31+
- Zum Beispiel, falls sie in Ihrem Downloads-Ordner ist, geben Sie ein:
32+
```
33+
cd Downloads
34+
```
35+
und drücken Enter.
36+
- Um zu sehen, was im aktuellen Ordner ist, geben Sie `ls` ein und drücken Enter.
37+
38+
4. **Anwendung ausführen**:
39+
- Im Terminal geben Sie ein:
40+
```
41+
docker compose up -d
42+
```
43+
und drücken Enter.
44+
- Möglicherweise müssen Sie es mit sudo ausführen: `sudo docker compose up -d`
45+
- Dieser Befehl lädt das erforderliche Docker-Image herunter und startet die Anwendung im Hintergrund. Beim ersten Mal kann es einige Minuten dauern.
46+
47+
5. **Anwendung aufrufen**:
48+
- Öffnen Sie Ihren Webbrowser (z.B. Firefox oder Chrome).
49+
- Geben Sie in die Adressleiste [http://localhost:3000](http://localhost:3000) ein und drücken Enter.
50+
- Die BetterBahn-Anwendung sollte laden.
51+
52+
6. **Anwendung stoppen (falls erforderlich)**:
53+
- Um die Anwendung zu stoppen, gehen Sie zurück zum Terminal und geben ein:
54+
```
55+
docker compose down
56+
```
57+
(oder `sudo docker compose down`)
58+
und drücken Enter.
59+
60+
## Fehlerbehebung
61+
62+
- Falls Sie Berechtigungsfehler erhalten, versuchen Sie die Befehle mit `sudo` auszuführen.
63+
- Falls Docker nicht läuft, starten Sie es mit `sudo systemctl start docker` (auf Systemen mit systemd).
64+
- Falls Port 3000 bereits verwendet wird, können Sie die Port-Zuordnung in der `docker-compose.yaml`-Datei ändern.
65+
- Falls ein Befehl nicht funktioniert, stellen Sie sicher, dass Sie ihn genau so eingeben, wie gezeigt, inklusive Leerzeichen.
66+
- Um das Terminal zu schließen, geben Sie `exit` ein und drücken Enter.

‎docs/Linux-Installation-en.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Linux Installation Guide
2+
3+
This guide will help you install and run BetterBahn on Linux using Docker. We'll explain every step in detail, assuming you're new to using the command line.
4+
5+
## Prerequisites
6+
7+
- A Linux distribution (Ubuntu, Fedora, etc.)
8+
- Docker installed on your system. If not, follow the instructions at [https://docs.docker.com/engine/install/](https://docs.docker.com/engine/install/) for your distribution.
9+
- Docker Compose (usually included with Docker, or install separately if needed).
10+
- Ensure Docker is running: Open a terminal and run `sudo systemctl start docker` (if using systemd).
11+
12+
## Installation Steps
13+
14+
1. **Open a Terminal**:
15+
- Press Ctrl+Alt+T (on most Linux distributions) to open a terminal window.
16+
- If that doesn't work, look for "Terminal" in your applications menu.
17+
18+
2. **Download the Docker Compose File**:
19+
- In the terminal, type the following command and press Enter:
20+
```
21+
curl -o docker-compose.yaml https://raw.githubusercontent.com/AWildLeon/betterbahn/main/docker-compose/docker-compose.yaml
22+
```
23+
This will download the file to your current directory (usually your home folder).
24+
- If curl is not installed, you can install it with `sudo apt install curl` (on Ubuntu/Debian) or equivalent for your distribution.
25+
- Alternatively, download it manually:
26+
- Open your web browser and go to [https://raw.githubusercontent.com/AWildLeon/betterbahn/main/docker-compose/docker-compose.yaml](https://raw.githubusercontent.com/AWildLeon/betterbahn/main/docker-compose/docker-compose.yaml).
27+
- Right-click on the page and select "Save Link As..." to save the file as `docker-compose.yaml` in a folder you can easily find, like your Downloads or Desktop.
28+
29+
3. **Navigate to the Folder (if downloaded manually)**:
30+
- If you downloaded the file to a specific folder, you need to go to that folder in the terminal.
31+
- For example, if it's in your Downloads folder, type:
32+
```
33+
cd Downloads
34+
```
35+
and press Enter.
36+
- To see what's in the current folder, type `ls` and press Enter.
37+
38+
4. **Run the Application**:
39+
- In the terminal, type:
40+
```
41+
docker compose up -d
42+
```
43+
and press Enter.
44+
- You might need to run it with sudo: `sudo docker compose up -d`
45+
- This command will pull the necessary Docker image and start the application in the background. It might take a few minutes the first time.
46+
47+
5. **Access the Application**:
48+
- Open your web browser (like Firefox or Chrome).
49+
- In the address bar, type [http://localhost:3000](http://localhost:3000) and press Enter.
50+
- The BetterBahn application should load.
51+
52+
6. **Stop the Application (when needed)**:
53+
- To stop the application, go back to the terminal and type:
54+
```
55+
docker compose down
56+
```
57+
(or `sudo docker compose down`)
58+
and press Enter.
59+
60+
## Troubleshooting
61+
62+
- If you get permission errors, try running the commands with `sudo`.
63+
- If Docker is not running, start it with `sudo systemctl start docker` (on systems with systemd).
64+
- If port 3000 is already in use, you can change the port mapping in the `docker-compose.yaml` file.
65+
- If a command doesn't work, make sure you're typing it exactly as shown, including spaces.
66+
- To close the terminal, type `exit` and press Enter.

‎docs/Windows-Installation-de.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Windows-Installationsanleitung
2+
3+
Diese Anleitung hilft Ihnen, BetterBahn auf Windows mit Docker Desktop zu installieren und auszuführen. Wir erklären jeden Schritt im Detail, als ob Sie neu bei der Befehlszeile sind.
4+
5+
## Voraussetzungen
6+
7+
- Windows 10 oder neuer (64-Bit)
8+
- Docker Desktop für Windows installiert. Sie können es von [https://www.docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop) herunterladen.
9+
- Stellen Sie sicher, dass Docker Desktop läuft und für die Verwendung von Linux-Containern konfiguriert ist (Standard).
10+
11+
## Installationsschritte
12+
13+
1. **Eingabeaufforderung öffnen**:
14+
- Drücken Sie die Windows-Taste auf Ihrer Tastatur (normalerweise zwischen Strg und Alt).
15+
- Geben Sie "cmd" ein und drücken Sie Enter.
16+
- Ein schwarzes Fenster namens "Eingabeaufforderung" sollte sich öffnen. Hier geben Sie die Befehle ein.
17+
18+
2. **Docker Compose-Datei herunterladen**:
19+
- Im Eingabeaufforderungsfenster geben Sie den folgenden Befehl ein und drücken Enter:
20+
```
21+
curl -o docker-compose.yaml https://raw.githubusercontent.com/l2xu/betterbahn/main/docker-compose/docker-compose.yaml
22+
```
23+
Dies lädt die Datei in Ihr aktuelles Verzeichnis herunter (normalerweise Ihr Benutzerordner).
24+
- Falls curl nicht funktioniert, können Sie sie manuell herunterladen:
25+
- Öffnen Sie Ihren Webbrowser und gehen Sie zu [https://raw.githubusercontent.com/l2xu/betterbahn/main/docker-compose/docker-compose.yaml](https://raw.githubusercontent.com/l2xu/betterbahn/main/docker-compose/docker-compose.yaml).
26+
- Rechtsklicken Sie auf die Seite und wählen Sie "Speichern unter...", um die Datei als `docker-compose.yaml` in einem leicht zu findenden Ordner zu speichern, z.B. Desktop oder Dokumente.
27+
28+
3. **In den Ordner navigieren (falls manuell heruntergeladen)**:
29+
- Falls Sie die Datei in einen bestimmten Ordner heruntergeladen haben, müssen Sie in der Eingabeaufforderung dorthin gehen.
30+
- Zum Beispiel, falls sie auf Ihrem Desktop ist, geben Sie ein:
31+
```
32+
cd Desktop
33+
```
34+
und drücken Enter.
35+
- Um zu sehen, was im aktuellen Ordner ist, geben Sie `dir` ein und drücken Enter.
36+
37+
4. **Anwendung ausführen**:
38+
- In der Eingabeaufforderung geben Sie ein:
39+
```
40+
docker compose up -d
41+
```
42+
und drücken Enter.
43+
- Dieser Befehl lädt das erforderliche Docker-Image herunter und startet die Anwendung im Hintergrund. Beim ersten Mal kann es einige Minuten dauern.
44+
45+
5. **Anwendung aufrufen**:
46+
- Öffnen Sie Ihren Webbrowser (z.B. Chrome, Edge oder Firefox).
47+
- Geben Sie in die Adressleiste [http://localhost:3000](http://localhost:3000) ein und drücken Enter.
48+
- Die BetterBahn-Anwendung sollte laden.
49+
50+
6. **Anwendung stoppen (falls erforderlich)**:
51+
- Um die Anwendung zu stoppen, gehen Sie zurück zur Eingabeaufforderung und geben ein:
52+
```
53+
docker compose down
54+
```
55+
und drücken Enter.
56+
57+
## Fehlerbehebung
58+
59+
- Falls Sie Probleme mit Docker haben, stellen Sie sicher, dass Docker Desktop läuft und dass die Virtualisierung in Ihrem BIOS aktiviert ist.
60+
- Bei Windows Home Edition müssen Sie möglicherweise WSL2 aktivieren. Folgen Sie den Anweisungen auf der Docker Desktop-Website.
61+
- Falls Port 3000 bereits verwendet wird, können Sie die Port-Zuordnung in der `docker-compose.yaml`-Datei ändern.
62+
- Falls ein Befehl nicht funktioniert, stellen Sie sicher, dass Sie ihn genau so eingeben, wie gezeigt, inklusive Leerzeichen.
63+
- Um die Eingabeaufforderung zu schließen, geben Sie `exit` ein und drücken Enter.

‎docs/Windows-Installation-en.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# Windows Installation Guide
2+
3+
This guide will help you install and run BetterBahn on Windows using Docker Desktop. We'll explain every step in detail, assuming you're new to using the command line.
4+
5+
## Prerequisites
6+
7+
- Windows 10 or later (64-bit)
8+
- Docker Desktop for Windows installed. You can download it from [https://www.docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop).
9+
- Ensure Docker Desktop is running and configured to use Linux containers (default).
10+
11+
## Installation Steps
12+
13+
1. **Open Command Prompt**:
14+
- Press the Windows key on your keyboard (usually between Ctrl and Alt).
15+
- Type "cmd" and press Enter.
16+
- A black window called "Command Prompt" should open. This is where you'll type commands.
17+
18+
2. **Download the Docker Compose File**:
19+
- In the Command Prompt window, type the following command and press Enter:
20+
```
21+
curl -o docker-compose.yaml https://raw.githubusercontent.com/l2xu/betterbahn/main/docker-compose/docker-compose.yaml
22+
```
23+
This will download the file to your current directory (usually your user folder).
24+
- If curl doesn't work, you can download it manually:
25+
- Open your web browser and go to [https://raw.githubusercontent.com/l2xu/betterbahn/main/docker-compose/docker-compose.yaml](https://raw.githubusercontent.com/l2xu/betterbahn/main/docker-compose/docker-compose.yaml).
26+
- Right-click on the page and select "Save as..." to save the file as `docker-compose.yaml` in a folder you can easily find, like your Desktop or Documents.
27+
28+
3. **Navigate to the Folder (if downloaded manually)**:
29+
- If you downloaded the file to a specific folder, you need to go to that folder in Command Prompt.
30+
- For example, if it's on your Desktop, type:
31+
```
32+
cd Desktop
33+
```
34+
and press Enter.
35+
- To see what's in the current folder, type `dir` and press Enter.
36+
37+
4. **Run the Application**:
38+
- In the Command Prompt, type:
39+
```
40+
docker compose up -d
41+
```
42+
and press Enter.
43+
- This command will pull the necessary Docker image and start the application in the background. It might take a few minutes the first time.
44+
45+
5. **Access the Application**:
46+
- Open your web browser (like Chrome, Edge, or Firefox).
47+
- In the address bar, type [http://localhost:3000](http://localhost:3000) and press Enter.
48+
- The BetterBahn application should load.
49+
50+
6. **Stop the Application (when needed)**:
51+
- To stop the application, go back to the Command Prompt and type:
52+
```
53+
docker compose down
54+
```
55+
and press Enter.
56+
57+
## Troubleshooting
58+
59+
- If you encounter issues with Docker, ensure that Docker Desktop is running and that virtualization is enabled in your BIOS.
60+
- For Windows Home edition, you might need to enable WSL2. Follow the instructions on the Docker Desktop website.
61+
- If port 3000 is already in use, you can change the port mapping in the `docker-compose.yaml` file.
62+
- If a command doesn't work, make sure you're typing it exactly as shown, including spaces.
63+
- To close Command Prompt, type `exit` and press Enter.

0 commit comments

Comments
 (0)