waldbrandpraevention/frontend

Frontend für KIWA

Waldbrandprävention

Inhalt

• Features ✨
• Demo
• Installation
  • 1-Line 🚀
  • Quickstart 🚀
  • Konfiguration ⚙️
    • Port ⚓
    • E-Mail 📨
    • Windkarte ☁️
  • Updates 🔁
  • Reverse Proxy 🛡️
  • FAQ ❓
• Development
  • Projekt Setup
  • E2E Testing
    • Code Coverage
  • Themes
  • Kacheln
  • Docker Compose

Features

• Sehr gute Performance auch bei riesigen Datensätzen.
• Gemeindegrenzen als Zonen einfach hinzufügen und entfernen
• Drohnen mit animierten Routen
• Alle Komponenten containerisiert
• Advanced Analyse Seite mit Drohnenbildern und KI-Einschätzungen
• Benachrichtigungen bei Brandereignissen
• Viele Karten: OpenStreetMap, Topografie, Satelliten und mehr
• Feuerwehrkarte mit Position von Feuerwehrwachen und Hydranten
• aktuelle Wetterdaten und Vorhersagen vom deutschen Wetterdienst
• animierte Windkarte mit dazugehörigem Windserver
• Authentifizierung mit Rollenverteilung (Benutzer und Administrator)
• Administration mit Organisations- und Usermanagement
• E-Mail Verifizierung
• Simulation der Drohnen und Events.
• Frei anpassbares Design mit vielen Themes
• Komplett modulares Kachellayout
• E2E-Testing

Demo

kiwa.tech

E-Mail: admin@kiwa.tech Passwort: adminkiwa

Installation

Am Einfachsten ist die Installation mit Docker (compose).

Die Images für Front- und Backend werden automatisch mit der jeweils aktuellen Version des Front- bzw. Backend Repos gebaut und auf Docker Hub hochgeladen. Alternativ können auch die jeweiligen Dockerfiles genutzt werden um die Images manuell zu erstellen. Die Anwendung wird mit docker compose und nginx als Reverse Proxy ausgeführt.

Zunächst muss docker compose installiert sein. Ist standardmäßig bei Docker Desktop der Fall.

One-Line Demo

Für eine schnelle Demo kann einfach folgender Befehl genutzt werden. Alle erstellten Container & Volumes werden automatisch bereinigt.

curl -fsSL https://raw.githubusercontent.com/waldbrandpraevention/frontend/main/install.sh | bash -

Auf localhost:8080 mit admin@kiwa.tech und adminkiwa anmelden.

Installationsskript verwendet docker-compose.demo.yml.

Deployment

Voraussetzungen

• x64 Architektur (AMD/Intel)
• minimum 4GB RAM
• minimum 2 vCPUs

1. Die Datei docker-compose.yml (für Deployment/Production) herunterladen.

2. Environment Variablen anpassen.

3. docker compose up

Falls die Anwendung im Hintergrund ausgeführt werden soll, kann -d an den Befehl angehängt werden.

Komponente	URL
Frontend	http://localhost:8080
API	http://localhost:8080/api/
API Dokumentation	http://localhost:8080/api/docs
Mail (nur Demo)	http://localhost:8025

Sie können sich nun mit den in ADMIN_MAIL und ADMIN_PASSWORD gesetzten Zugangsdaten anmelden. Diese sollten nach erfolgreichem Login auf jeden Fall geändert werden.

Konfiguration

Port

Einstellungen können als Environmentvariablen in der docker-compose.yml angepasst werden.

Um den Port der Anwendung zu ändern, kann die obige Datei so geändert werden

...
frontend:
  image: waldbrandpraevention/frontend
  ports:
-   - 8080:80 
+   - 1234:80
...

E-Mail

Um den E-Mail Versand lokal testen zu können, wird Mailhog mitinstalliert. Dieser dient nur für Demozwecke und muss später durch einen vorhandenen Mailserver ausgetauscht werden. Daher die docker-compose.yml folgendermaßen anpassen:

services:
 backend:
    image: waldbrandpraevention/backend
    command: uvicorn main:app --host 0.0.0.0 --port 8000 --root-path /api
    environment:
      - ADMIN_MAIL=admin@kiwa.tech 
      - ADMIN_PASSWORD=adminkiwa
      - ADMIN_ORGANIZATION=KIWA
    expose:
      - 8000
   environment:
      - ...
+     - SMTP_HOST=domain.tld
+     - SMTP_USER=
+     - SMTP_PASSWORD=
+     - SMTP_PORT=25
+     - SMTP_SENDER=no-reply@domain.tld

Windkarte

Die Windkarte basiert auf leaflet-velocity und benötigt Winddaten im GRIB2-JSON Format.

Um die Daten der Windkarte zu laden lässt sich einfach ein Wind Server aufsetzen, welcher stets aktuelle Winddaten vom Wetterdienst abruft.

Deployment und weitere Informationen dazu im Repo waldbrandpraevention/wind-js-server

Im Projekt wird eine Instanz (https://wind.bp.adriansoftware.de) von diesem Server verwendet.

Die Server URL kann in der .env.production bzw. .env.development unter REACT_APP_WIND_DATA geändert werden.

Die docker-compose.yml und docker-compose.demo.yml enthalten bereits den fertig konfigurierten Server.

Updates

So wird die Anwendung aktualisiert:

1. Container stoppen und entfernen.

Achtung! Alle Daten in der Datenbank werden dabei gelöscht.

docker compose down -v

oder falls die Datenbank erhalten bleiben soll:

docker compose down

2. Container aktualisieren & starten

docker compose pull && docker compose up -d

Reverse Proxy

Um die Anwendung hinter einer Reverse Proxy zu verwenden kann für Apache folgende vHost Konfiguration verwendet werden:

<VirtualHost *:80>
    ServerName domain.tld

    # Alle HTTP Anfragen zu HTTPS weiterleiten
    RewriteEngine on
    RewriteCond %{SERVER_NAME} =domain.tld
    RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
</VirtualHost>

<VirtualHost *:443>
    ServerName domain.tld
    ProxyPass / http://127.0.0.1:8080/
    ProxyPassReverse / http://127.0.0.1:8080/

    ProxyPreserveHost on

    ErrorLog ${APACHE_LOG_DIR}/wb-error.log
    CustomLog ${APACHE_LOG_DIR}/wb-access.log combined

    # Für Let's Encrypt Zertifikate
    SSLEngine on
    SSLCertificateFile /etc/letsencrypt/live/domain.tld/fullchain.pem
    SSLCertificateKeyFile /etc/letsencrypt/live/domain.tld/privkey.pem
    Include /etc/letsencrypt/options-ssl-apache.conf

    Header always set Strict-Transport-Security "max-age=31536000"
    Header always set X-Frame-Options "deny"
    Header always set X-XSS-Protection "1; mode=block"
    Header always set X-Content-Type-Options "nosniff"
    Header always set Referrer-Policy "strict-origin-when-cross-origin"
</VirtualHost>

Development

Projekt Setup

1. GitHub Repo clonen

git clone https://github.com/waldbrandpraevention/frontend.git

2. Dependencies installieren

npm install

3. npm start zum Starten.
   npm run cypress zum Testen.
   npm run build zum Erstellen.

E2E Testing

1. npm start (Wichtig!)

2. npm run cypress

3. E2E Testing auswählen

4. Browser auswählen. Empfohlen: Chrome.

5. Ein Spec auswählen zum Testen.

Mehr Infos: https://cypress.io

Code Coverage

1. npm run cypress:run

2. Report in coverage/lcov-report/index.html

Themes

Um ein Theme zu erstellen folgendermaßen vorgehen:

1. src/service/stores.ts

export const themes: { black: Theme, /* ... */, custom: Theme } = {
  black: {
    background: "#FAFAFA",
    headerBackground: "#FAFAFA",
    sidebarBackground: "#000000",
    sidebarActive: "#383838",
    sidebarHover: "#5c5c5c",
    sidebarText: "#FFFFFF",
  }
  /* ... */
  custom: {
    background: "#ecf8f0",
    headerBackground: "#ecf8f0",
    sidebarBackground: "#009688",
    sidebarActive: "#4DB6AC",
    sidebarHover: "#80CBC4",
    sidebarText: "#FFFFFF",
  }
}

2. src/components/tiles/account/ColorCustomizer.tsx

// fast am Ende der Datei:
<InputGroup>
  <Button
    style={{ border: "none", color: "white", background: "#000000" }}
    onClick={() => colors.setColor({ ...themes.black })}
  >
    <TbColorSwatch /> Schwarz
  </Button>
  /* ... */
  <Button
    style={{ border: "none", color: "white", background: "#ecf8f0" }}
    onClick={() => colors.setColor({ ...themes.custom })}
  >
    <TbColorSwatch /> Mein Custom Theme
  </Button>
</InputGroup>;

Kacheln

Das Kachellayout ist komplett modular aufgebaut.

So kann eine Kachel erstellt werden:

1. Im src/components/tiles eine Komponente erstellen, welche als direktem Child ein <Tile>...</Tile> returned.
2. Auf der gewünschten Seite src/pages/MyPage.tsx

import MyTile from "../components/tiles/MyTile";
const TilesLayout = lazy(() => import("../components/TilesLayout"));

const MyPage = () => {
  const { defaultTiles, defaultLayout } = tiles([
    {
      el: <MyTile />,
      id: "mytile",
      name: "My Tile",
      main: { x: 0, y: 0, w: 8, h: 3 },
      mobile: { x: 0, y: 0, w: 24, h: 3 },
    },
    // more tiles...
  ]);

  return (
    <div className="App">
      <Suspense fallback={<Loading />}>
        <TilesLayout
          layoutId="dashboard"
          defaultLayout={defaultLayout}
          defaultTiles={defaultTiles}
        />
      </Suspense>
    </div>
  );
};

export default MyPage;

Referenz:

export type TileElement = {
  /**
   * tile component in `components/tiles`. must return a `<Tile>...</Tile>`
   */
  el: ReactElement;
  /**
   * unique id per `<TilesLayout />`
   */
  id: string;
  /**
   * display name
   */
  name: string;
  /**
   * whether tile is enabled by default
   */
  enabled?: boolean;
  /**
   * don't show tile while in edit mode. show placeholder instead
   */
  noEditmode?: boolean;
};

export type TileLayouts = {
  /**
   * layout for desktop and tablet breakpoint
   */
  main: ReactGridLayout.Layout[];
  /**
   * layout for mobile breakpoint
   */
  mobile: ReactGridLayout.Layout[];
};

Docker Compose

Folgende docker-compose.yml Datei kann verwendet werden, um die Anwendung lokal zu starten mit einem bestimmten Git-Branch.

Folgende Datei kann veraltet sein. Daher die aktuelle docker-compose-yml beachten.

# Used for local demo -> see install.sh
version: '3'
name: Waldbrandpraevention

services:
  # React
  frontend:
    build: https://github.com/waldbrandpraevention/frontend.git#my-branch
    ports:
      - 8080:80

  # API
  backend:
    build: https://github.com/waldbrandpraevention/backend.git#my-branch
    command: uvicorn main:app --host 0.0.0.0 --port 8000 --root-path /api
    environment:
      - ADMIN_MAIL=admin@kiwa.tech 
      - ADMIN_PASSWORD=adminkiwa
      - ADMIN_ORGANIZATION=KIWA
      - DB_PATH=testing.db
      - DB_BACKUP_PATH=backuptest.db
      - DEMO_LONG=12.68895149
      - DEMO_LAT=52.07454738
      - GEOJSON_PATH=/database/zone_data.geojson
      - DEMO_DISTRICT=Landkreis Potsdam-Mittelmark
      - DOMAIN=localhost:8080
      - SMTP_HOST=mailhog
      - SMTP_USER=mailhog
      - SMTP_PASSWORD=mailhog
      - SMTP_PORT=1025
      - SMTP_SENDER=no-reply@kiwa.local

  # Mail (optional, nur für lokale Demo ohne vorhandenem Mailserver)
  mailhog:
    image: mailhog/mailhog
    ports:
      - 1025:1025 # smtp server
      - 8025:8025 # web ui