# 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 https://git-scm.com/install/windows 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 https://brew.sh/ 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 ``` Falls `docker run` mit ```text permission denied while trying to connect to the docker API at unix:///var/run/docker.sock ``` abbricht, zunächst prüfen: ```bash ls -l /var/run/docker.sock id getent group docker ``` Ist der Benutzer bereits Mitglied der Gruppe `docker`, die Gruppe aber bei `id` noch nicht aufgeführt, wurde die Gruppenmitgliedschaft von der aktuellen Shell noch nicht übernommen. Dann entweder: ```bash newgrp docker ``` ausführen oder WSL vollständig neu starten. Dazu in PowerShell: ```powershell wsl --shutdown ``` Danach Ubuntu erneut öffnen und `docker run --rm hello-world` wiederholen. > 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 > **Wichtig für WSL-Nutzer:** > Wenn Ubuntu unter Windows über WSL 2 läuft und Docker Desktop verwendet wird, **nicht** mit diesem Abschnitt weitermachen. Dieser Abschnitt ist nur für eigenständige Linux-Installationen vorgesehen. **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: > https://docs.docker.com/engine/install/debian/ --- ### 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: https://docs.docker.com/desktop/setup/install/mac-install/ --- ## 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 CKAL_USERNAME= CKAL_PASSWORD= CKAL_CALENDAR_URL= ``` Die `.env` darf keine produktiven Secrets enthalten und sollte nicht ins Repository committed werden. > 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. 9. Läuft pgAdmin im Browser auf einem entfernten Server, kann die Backup-Datei 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 ### pgAdmin 4 installieren Falls pgAdmin 4 noch nicht installiert ist, kann es lokal als Desktop-Anwendung installiert werden. * **Windows:** pgAdmin-Installer herunterladen und ausführen. * **macOS:** pgAdmin-Disk-Image herunterladen, öffnen und die Anwendung installieren. * **Ubuntu/Linux:** pgAdmin kann über das offizielle APT-Repository installiert werden; für die lokale Nutzung reicht `pgadmin4-desktop`. Die Installationspakete und Anleitungen sind unter https://www.pgadmin.org/download/ verfügbar. Unter Windows mit WSL 2 kann pgAdmin direkt unter Windows installiert werden. Die PostgreSQL-Datenbank aus Docker ist anschließend über `localhost:5432` erreichbar. 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. 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: http://localhost:8080 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 ### Nach einem Neustart starten Nach einem Neustart von Windows oder macOS zuerst **Docker Desktop** starten und warten, bis Docker bereit ist. Unter einer eigenständigen Linux-Installation sicherstellen, dass der Docker-Dienst läuft. Danach im Projektroot die lokalen Container starten: ```bash docker compose -f docker-compose.local.yml up -d ``` Falls sich das `Dockerfile` seit dem letzten Start geändert hat oder die Images neu gebaut werden sollen: ```bash docker compose -f docker-compose.local.yml up -d --build ``` Anschließend kann das Intranet wieder unter http://localhost:8080 aufgerufen werden. ### 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.