Search Tool – Installationsanleitung

Durchsucht mehrere UniFi-Controller gleichzeitig nach MAC-Adressen, SSIDs, Sitenamen oder Gerätenamen. Läuft vollständig via Docker.

---

Voraussetzungen

| Anforderung | Details | |---|---| | Docker | ≥ 24.x | | Docker Compose | ≥ v2 (Plugin docker compose) | | Python 3 | Für manage.sh (Update-Logik, kein unzip nötig) | | RAM | Minimal (< 512 MB) |

Systemunterstützung

• Linux (Ubuntu 22.04+, Debian 11+, Rocky/AlmaLinux 9)
• UGREEN NAS (DXP- und NASync-Serie mit Docker-Unterstützung)
• Synology NAS (DSM 7.2+, Container Manager)
• Proxmox LXC (mit Docker installiert)

---

Verzeichnisstruktur nach Installation

searchtool/                     ← Installationsordner
├── manage.sh                   ← Management-Skript
├── docker-compose.yaml
├── .env                        ← aus .env.example angelegt (beim ersten Update)
├── .env.example                ← Vorlage (nie manuell anpassen!)
├── app.py
├── templates/
├── static/
└── data/                       ← persistente Daten (wird nie überschrieben)
    ├── users.json               Benutzer-Zugangsdaten
    ├── controllers.json         Verschlüsselte Controller-Zugangsdaten
    ├── .secret_key               Flask-Session-Key
    └── .fernet.key                Verschlüsselungs-Key für Controller-Passwörter

---

Neue Installation (Erst-Setup)

Schritt 1 – Installationsordner erstellen

mkdir -p /opt/searchtool
cd /opt/searchtool

UGREEN/Synology NAS: Empfohlener Pfad: /volume1/docker/searchtool

Schritt 2 – Dateien ablegen

Die searchtool_release.zip und manage.sh in den Installationsordner kopieren.

/opt/searchtool/
├── searchtool_release.zip
└── manage.sh

Schritt 3 – manage.sh ausführbar machen

chmod +x manage.sh

Schritt 4 – Erstes Update / Installation

./manage.sh update

Das Skript:

1. Entpackt die ZIP (via Python 3, kein unzip nötig)
2. Legt .env aus .env.example an (nur beim ersten Mal – bestehende .env bleibt unangetastet)
3. Baut das Docker-Image und startet den Container

Schritt 5 – Konfiguration anpassen

nano .env

Wichtige Werte:

TZ=Europe/Berlin
APP_PORT=5050

# Zufälligen Wert generieren: python3 -c "import secrets; print(secrets.token_hex(32))"
SECRET_KEY=change_me_to_a_random_secret

# Controller als JSON-Array (einzeilig)
# Jeder Controller braucht: name, url, username, password
# verify (optional, Standard: true) – auf false setzen bei self-signed Zertifikaten
CONTROLLERS=[{"name":"mein-controller","url":"https://unifi.example.com","username":"readonly","password":"geheim","verify":true}]

# Optionale Feineinstellungen
# REQUEST_TIMEOUT=12
# SEARCH_WORKERS=8
# PDF_MAX_ROWS=1500
# JOB_MAX_AGE_SECONDS=3600

Wichtig: SECRET_KEY muss ein langer zufälliger Wert sein — ohne eigenen SECRET_KEY generiert die App beim ersten Start automatisch einen persistenten Schlüssel unter data/.secret_key.

Die Controller aus CONTROLLERS werden beim ersten Start einmalig in data/controllers.json importiert (verschlüsselt). Danach lassen sie sich bequem über die Weboberfläche unter Admin verwalten (hinzufügen, bearbeiten, löschen, per JSON-Datei importieren) — CONTROLLERS in der .env wird danach nicht mehr benötigt.

Schritt 6 – Container neu starten (nach Konfigurationsänderung)

./manage.sh restart

---

Erreichbarkeit

| Dienst | URL | |---|---| | UniFi Search Tool | http://<IP-Adresse>:5055 |

Standard-Login: admin / admin — bitte nach dem ersten Login sofort über Admin → Benutzer ändern.

---

Update (bestehende Installation)

1. Neue searchtool_release.zip in den Installationsordner legen
2. Update starten:

./manage.sh update

Was passiert beim Update:

• Code-Dateien (app.py, templates/, static/, …) werden aktualisiert
• .env bleibt unverändert (wird nicht überschrieben)
• data/-Ordner wird nicht berührt (Benutzer, Controller, Schlüssel bleiben erhalten)
• Docker-Image wird neu gebaut und der Container neu gestartet
• Die ZIP wird nach dem Update umbenannt (als Archiv, *.deployed_<Zeitstempel>.zip)

---

Watch-Modus (automatische Updates)

Der Watch-Modus prüft alle 30 Sekunden, ob eine neue searchtool_release.zip vorhanden ist, und deployt sie automatisch.

./manage.sh watch

Zum Starten als Hintergrunddienst:

nohup ./manage.sh watch > logs/watch.log 2>&1 &

---

manage.sh – Alle Befehle

./manage.sh update              # Update aus searchtool_release.zip
./manage.sh update datei.zip    # Update aus bestimmter ZIP
./manage.sh watch               # Watch-Modus: neue ZIP → auto deploy
./manage.sh start               # Container starten
./manage.sh stop                # Container stoppen
./manage.sh restart             # Container neu starten
./manage.sh status              # Container-Status anzeigen
./manage.sh logs                # Logs anzeigen (live)

---

Features

• Parallele Suche über mehrere UniFi-Controller und Sites (MAC, SSID, Site, Gerätename)
• Standort-Gruppierung: Geräte werden innerhalb einer Site automatisch nach erkanntem Standort (Straße + Hausnummer) gruppiert
• Automatische Ersatzgeräte-Vorschläge für auslaufende Legacy-Modelle (Spalte „Ersatz“)
• Export als CSV und PDF (inkl. Standort-Gruppierung und Ersatz-Spalte)
• Gerätemodell-Mapping mit automatischer Erkennung fehlender Modellnamen
• Benutzerverwaltung (Rollen: admin/user), Login auch gegen System-Benutzer (/etc/shadow) möglich
• SSO-Anbindung (Token-basiert) für Einbindung in andere Tools
• Light/Dark Mode

---

Fehlerbehebung

Container startet nicht

./manage.sh logs

Login schlägt fehl / Passwort vergessen

Admin-Zugangsdaten liegen in data/users.json (bcrypt-Hash). Neuen Hash erzeugen:

python3 -c "import bcrypt; print(bcrypt.hashpw(b'neues_passwort', bcrypt.gensalt()).decode())"

und in data/users.json beim gewünschten Benutzer eintragen, danach ./manage.sh restart.

Controller-Login schlägt fehl

• URL in Admin prüfen (muss z. B. https://unifi.example.com:8443 inkl. Port sein, ohne abschließenden /)
• Bei selbstsigniertem Zertifikat: „SSL-Zertifikat verifizieren“ deaktivieren
• Controller-Firewall: Zugriff vom Server, auf dem das Search Tool läuft, muss erlaubt sein

Port 5055 nicht erreichbar

./manage.sh status
docker compose ps

docker compose nicht gefunden

docker compose version
# Falls nicht vorhanden, Docker aktualisieren oder Compose-Plugin installieren

UGREEN NAS: Permission denied bei manage.sh

chmod +x manage.sh
# Oder direkt ausführen:
sh manage.sh update

---

Deinstallation

./manage.sh stop
docker compose down --volumes --rmi all

Achtung: --volumes löscht alle persistenten Daten inkl. Benutzer und Controller-Zugangsdaten. Ohne --volumes bleiben die Daten im data/-Ordner erhalten.