# Intranet lokal aufsetzen # 0. Git installieren und Repository klonen Bevor das Intranet lokal eingerichtet werden kann, muss Git installiert und das Repository heruntergeladen werden. ## Windows Git for Windows kann direkt über `winget` installiert werden: ```powershell winget install --id Git.Git -e --source winget ``` Alternativ kann **Git for Windows** über heruntergeladen und installiert werden. Nach der Installation PowerShell, Windows Terminal oder Git Bash neu öffnen und prüfen: ```bash git --version ``` > Wird das Projekt anschließend mit Docker über WSL 2 verwendet, empfiehlt es sich, auch das Repository innerhalb des WSL-Dateisystems zu klonen, z. B. unter `~/src/intranet`. ### macOS Falls Homebrew noch nicht installiert ist, die Installationsanleitung unter verwenden. Git über Homebrew installieren: ```bash brew install git ``` Danach prüfen: ```bash git --version ``` ## Git konfigurieren Beim ersten Einrichten den eigenen Namen und die E-Mail-Adresse für Commits hinterlegen: ```bash git config --global user.name "Vorname Nachname" git config --global user.email "name@example.com" ``` ## Repository klonen ### macOS / Linux / WSL ```bash cd ~/Documents git clone https://git.pelpino.de/NAK-Reinickendorf/intranet.git cd intranet ``` ### Windows ```powershell cd $HOME\Documents git clone https://git.pelpino.de/NAK-Reinickendorf/intranet.git cd intranet ``` Beim Klonen über HTTPS können Benutzername und Personal Access Token abgefragt werden. Als Passwort wird in diesem Fall der **Token**, nicht das normale Account-Passwort verwendet. ## HTTPS-Zugangsdaten speichern ### macOS ```bash git config --global credential.helper osxkeychain ``` Beim nächsten Zugriff einmal Benutzername und Token eingeben. Anschließend werden die Zugangsdaten im macOS-Schlüsselbund gespeichert. ### Windows Git for Windows enthält den **Git Credential Manager**. Bei der ersten Authentifizierung können die Zugangsdaten darüber sicher gespeichert werden. ## Repository prüfen ```bash git status git remote -v ``` Das Remote Repository sollte auf folgende Adresse verweisen: ```text https://git.pelpino.de/NAK-Reinickendorf/intranet.git ``` --- ## 2. Docker installieren ### Windows + WSL 2 — empfohlen PowerShell als Administrator: ```powershell wsl --install -d Ubuntu-24.04 wsl --update ``` Windows neu starten und prüfen: ```powershell wsl -l -v ``` Ubuntu muss mit **WSL-Version 2** laufen. Falls `Ubuntu-24.04` über `wsl --install` nicht installiert werden kann, Ubuntu 24.04 alternativ über den Microsoft Store installieren. Danach **Docker Desktop for Windows** installieren und das WSL-2-Backend verwenden. In Docker Desktop: ```text Settings → Resources → WSL Integration ``` Integration für Ubuntu aktivieren und in WSL testen: ```bash docker --version docker compose version docker run --rm hello-world ``` > Docker Engine nicht zusätzlich innerhalb von WSL installieren, wenn Docker Desktop verwendet wird. > > Für bessere Dateisystem-Performance das Repository möglichst im WSL-Dateisystem ablegen, z. B. `~/src/intranet`, nicht unter `/mnt/c/...`. --- ### Linux — Ubuntu 24.04 LTS **1. Konfliktierende Pakete entfernen** ```bash sudo apt remove docker.io docker-compose docker-compose-v2 docker-doc docker-buildx podman-docker containerd runc ``` **2. Voraussetzungen installieren** ```bash sudo apt update sudo apt install ca-certificates curl -y ``` **3. Docker GPG-Key hinzufügen** ```bash sudo install -m 0755 -d /etc/apt/keyrings sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \ -o /etc/apt/keyrings/docker.asc sudo chmod a+r /etc/apt/keyrings/docker.asc ``` **4. Docker-Repository einrichten** ```bash sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null < **Debian 13:** Das Projekt funktioniert ebenfalls unter Debian. Dafür das Docker-Repository entsprechend auf `linux/debian` umstellen: > --- ### macOS 1. **Docker Desktop for Mac** passend für Apple Silicon oder Intel installieren. 2. Docker Desktop starten. 3. Im Terminal testen: ```bash docker --version docker compose version docker run --rm hello-world ``` Dokumentation: --- ## 3. Lokale Docker-Konfiguration Im Projektroot müssen folgende Dateien liegen: ```text Dockerfile docker-compose.yml docker-compose.local.yml web/ ``` Die produktive `docker-compose.yml` wird lokal **nicht** verwendet. Dadurch werden insbesondere folgende Produktionsbestandteile nicht gestartet: - `scheduler` - `dokploy-network` - Strato-SSH - produktive Scheduler-Secrets Die lokale Compose-Datei startet ausschließlich: - `web` - `db` (PostgreSQL 18 mit pgvector) Sie verwendet denselben `Dockerfile` wie Produktion. Der Web-Container ist lokal unter `127.0.0.1:8080` erreichbar. PostgreSQL wird für pgAdmin unter `127.0.0.1:5432` freigegeben. Für die Datenbank wird das Image `pgvector/pgvector:pg18` verwendet, weil der Produktiv-Dump die PostgreSQL-Erweiterung `vector` benötigt. PostgreSQL 18 verwendet für persistente Daten den Mount-Punkt: ```text /var/lib/postgresql ``` Nicht verwenden: ```text /var/lib/postgresql/data ``` Durch den Bind-Mount ```text ./web → /var/www/html ``` werden Änderungen an PHP, CSS und JavaScript ohne erneuten Image-Build sichtbar. Laufzeitdaten wie Profilbilder und Aushänge liegen weiterhin in lokalen Docker-Volumes. --- ## 4. Environment-Variablen anlegen Im Projektroot eine `.env` anlegen: ```dotenv # PostgreSQL POSTGRES_VERSION=18 DB_NAME=intranet DB_USER=intranet DB_PASSWORD=local-dev-password # Intranet INTRANET_FQDN=localhost:8080 # Lokale Dummy-Werte für externe Dienste SMTP_HOST=127.0.0.1 SMTP_PORT=1025 SMTP_USER=local SMTP_PASSWORD=local ADMIN_EMAIL=local@example.invalid SMS_GATEWAY_URL=http://127.0.0.1:9 HA_BASE_URL=http://127.0.0.1:9 HA_TOKEN=local OPENWEATHER_API_KEY=local ``` Die `.env` darf keine produktiven Secrets enthalten und sollte nicht ins Repository committed werden. ### PostgreSQL-Version prüfen Lokal sollte möglichst dieselbe PostgreSQL-Major-Version wie in Produktion verwendet werden. Wir verwenden **PostgreSQL 18**. --- ## 5. Produktivdatenbank mit pgAdmin sichern In pgAdmin: 1. Produktivserver öffnen. 2. Unter **Databases** die Intranet-Datenbank rechtsklicken. 3. **Backup…** auswählen. 4. Datei außerhalb des Repositorys speichern, z. B. `intranet.dump`. 5. **Format: Custom** wählen. 6. Unter **Data Options → Do not save**: - **Owner: Yes** - **Privileges: Yes** 7. **Include CREATE DATABASE statement: No** lassen. 8. **Backup** starten. Wenn pgAdmin im Browser auf einem entfernten Server läuft, wird die Backup-Datei serverseitig gespeichert. Sie kann anschließend über **Tools → Storage Manager** heruntergeladen werden. > Der Dump enthält Produktivdaten. Nicht committen, weitergeben oder in ungeschützten Cloud-Ordnern speichern. --- ## 6. Lokale Datenbank starten Im Projektroot: ```bash docker compose -f docker-compose.local.yml up -d db ``` Status prüfen: ```bash docker compose -f docker-compose.local.yml ps ``` Der Datenbank-Container sollte nach einigen Sekunden den Status `healthy` anzeigen. Optional kann geprüft werden, ob pgvector verfügbar ist: ```bash docker exec -it intranet-local-db-1 psql -U intranet -d intranet -c "CREATE EXTENSION IF NOT EXISTS vector;" ``` --- ## 7. Dump mit pgAdmin importieren In pgAdmin einen neuen Server registrieren: ```text Host: localhost Port: 5432 Maintenance database: intranet Username: intranet Password: local-dev-password ``` Die Werte müssen den Angaben in `.env` entsprechen. Danach: 1. Lokale Datenbank `intranet` rechtsklicken. 2. **Restore…** auswählen. 3. **Format: Custom or tar** wählen. 4. `intranet.dump` auswählen. 5. Unter **Data Options → Do not save**: - **Owner: Yes** - **Privileges: Yes** 6. **Include CREATE DATABASE statement: No**. 7. **Clean before restore: No** beim ersten Import. 8. **Restore** starten. Der Restore sollte ohne Fehler zur fehlenden Extension `vector` durchlaufen. Falls `pg_restore` mit `extension "vector" is not available` abbricht, prüfen, ob in `docker-compose.local.yml` tatsächlich `pgvector/pgvector:pg18` verwendet wird. Soll die lokale Datenbank später vollständig durch einen neuen Dump ersetzt werden, kann das lokale Setup zurückgesetzt werden: ```bash docker compose -f docker-compose.local.yml down -v docker compose -f docker-compose.local.yml up -d db ``` Danach den Dump erneut importieren. > **Achtung:** `down -v` löscht nicht nur PostgreSQL, sondern auch alle übrigen lokalen Intranet-Volumes, z. B. Profilbilder, Aushänge und andere Laufzeitdaten. Nur verwenden, wenn diese Daten bewusst verworfen werden sollen. --- ## 8. Intranet starten ```bash docker compose -f docker-compose.local.yml up -d --build ``` Status prüfen: ```bash docker compose -f docker-compose.local.yml ps ``` Aufrufen: Die Benutzer aus dem importierten Dump können anschließend für den Login verwendet werden. Die lokale Compose-Datei setzt `session.cookie_secure=0`, da lokal HTTP statt HTTPS verwendet wird. --- ## Entwicklung ### Status prüfen ```bash docker compose -f docker-compose.local.yml ps ``` ### Web-Logs anzeigen ```bash docker compose -f docker-compose.local.yml logs -f web ``` ### Datenbank-Logs anzeigen ```bash docker compose -f docker-compose.local.yml logs -f db ``` ### Änderungen an PHP, CSS und JavaScript Änderungen unter `web/` werden durch den Bind-Mount direkt in den laufenden Container übernommen. Ein Rebuild ist normalerweise nicht notwendig. Nach dem Speichern reicht in der Regel ein Reload im Browser. ### Änderungen am Dockerfile Nach Änderungen am `Dockerfile` neu bauen: ```bash docker compose -f docker-compose.local.yml up -d --build ``` ### Stoppen ```bash docker compose -f docker-compose.local.yml down ``` Die Docker-Volumes bleiben dabei erhalten. ### Komplett zurücksetzen ```bash docker compose -f docker-compose.local.yml down -v ``` > **Achtung:** Dabei werden alle lokalen Docker-Volumes des Projekts gelöscht, einschließlich der lokalen PostgreSQL-Datenbank.