NAK-Reinickendorf/intranet
2
0
Fork 0
Code Issues 2 Pull Requests Actions Projects 1 Wiki Activity

Merge pull request 'bugfix - tutorial fixed' (#5) from dev into main

Browse Source 
Reviewed-on: #5
Reviewed-by: Samuel Bias <samuel@bias-mail.de>
This commit was merged in pull request #5.
This commit is contained in:
samuelbias
2026-08-27 20:20:33 +02:00
parent 8038316ec9 5f8a414622
commit e5e8efe2d2
2 changed files with 171 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+169 -23
View File
@@ -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 <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
@@ -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 <<EOF
sudo tee /etc/apt/sources.list.d/docker.sources > /dev/null <<EOF2
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF
EOF2
sudo apt update
```
@@ -127,7 +223,7 @@ Dokumentation:
---
## 2. Lokale Docker-Konfiguration
## 3. Lokale Docker-Konfiguration
Im Projektroot müssen folgende Dateien liegen:
@@ -148,12 +244,26 @@ Die produktive `docker-compose.yml` wird lokal **nicht** verwendet. Dadurch werd
Die lokale Compose-Datei startet ausschließlich:
- `web`
- `db` (PostgreSQL)
- `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
@@ -164,13 +274,13 @@ werden Änderungen an PHP, CSS und JavaScript ohne erneuten Image-Build sichtbar
---
## 3. Environment-Variablen anlegen
## 4. Environment-Variablen anlegen
Im Projektroot eine `.env` anlegen:
```dotenv
# PostgreSQL
POSTGRES_VERSION=16
POSTGRES_VERSION=18
DB_NAME=intranet
DB_USER=intranet
DB_PASSWORD=local-dev-password
@@ -191,13 +301,15 @@ 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**.
---
## 4. Produktivdatenbank mit pgAdmin sichern
## 5. Produktivdatenbank mit pgAdmin sichern
In pgAdmin:
@@ -212,11 +324,13 @@ In pgAdmin:
7. **Include CREATE DATABASE statement: No** lassen.
8. **Backup** starten.
> 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:
<http://localhost:8080>
@@ -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
```
```
> **Achtung:** Dabei werden alle lokalen Docker-Volumes des Projekts gelöscht, einschließlich der lokalen PostgreSQL-Datenbank.
docker-compose.local.yml
+2 -2
View File
@@ -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