From ffb5cd336d5359586d3eed28d697201c7816852b Mon Sep 17 00:00:00 2001 From: leonie 3 Date: Thu, 27 Aug 2026 20:11:57 +0200 Subject: [PATCH] tutorial fixed --- README.md | 192 ++++++++++++++++++++++++++++++++++----- docker-compose.local.yml | 4 +- 2 files changed, 171 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index bd170f2..f45f35e 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,102 @@ # Intranet lokal aufsetzen -## 1. Docker installieren +# 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 @@ -70,14 +166,14 @@ 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 < /dev/null < Der Dump enthält Produktivdaten. Nicht committen oder weitergeben. +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. --- -## 5. Lokale Datenbank starten +## 6. Lokale Datenbank starten Im Projektroot: @@ -230,9 +344,17 @@ Status prüfen: 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;" +``` + --- -## 6. Dump mit pgAdmin importieren +## 7. Dump mit pgAdmin importieren In pgAdmin einen neuen Server registrieren: @@ -250,16 +372,18 @@ Danach: 1. Lokale Datenbank `intranet` rechtsklicken. 2. **Restore…** auswählen. -3. **Format: Custom**. +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** +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: +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 @@ -268,16 +392,22 @@ docker compose -f docker-compose.local.yml up -d db Danach den Dump erneut importieren. -> `down -v` löscht neben PostgreSQL auch die übrigen lokalen Intranet-Volumes. +> **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. --- -## 7. Intranet starten +## 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: @@ -290,34 +420,50 @@ Die lokale Compose-Datei setzt `session.cookie_secure=0`, da lokal HTTP statt HT ## Entwicklung -Status: +### Status prüfen ```bash docker compose -f docker-compose.local.yml ps ``` -Logs: +### 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 ``` -Normale Änderungen unter `web/` benötigen durch den Bind-Mount keinen Rebuild. - -Stoppen: +### Stoppen ```bash docker compose -f docker-compose.local.yml down ``` -Komplett zurücksetzen: +Die Docker-Volumes bleiben dabei erhalten. + +### Komplett zurücksetzen ```bash docker compose -f docker-compose.local.yml down -v -``` \ No newline at end of file +``` + +> **Achtung:** Dabei werden alle lokalen Docker-Volumes des Projekts gelöscht, einschließlich der lokalen PostgreSQL-Datenbank. diff --git a/docker-compose.local.yml b/docker-compose.local.yml index 744a116..a532162 100644 --- a/docker-compose.local.yml +++ b/docker-compose.local.yml @@ -36,7 +36,7 @@ services: - calendar_pdf:/var/www/html/pdf db: - image: postgres:${POSTGRES_VERSION:-16} + image: pgvector/pgvector:pg18 ports: - "127.0.0.1:5432:5432" environment: @@ -45,7 +45,7 @@ services: POSTGRES_USER: ${DB_USER:?set DB_USER in .env} POSTGRES_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD in .env} volumes: - - postgres_data:/var/lib/postgresql/data + - postgres_data:/var/lib/postgresql healthcheck: test: ["CMD-SHELL", "pg_isready -U \"$${POSTGRES_USER}\" -d \"$${POSTGRES_DB}\""] interval: 5s