470 lines
11 KiB
Markdown
470 lines
11 KiB
Markdown
# 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
|
|
```
|
|
|
|
> 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 <<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
|
|
EOF2
|
|
|
|
sudo apt update
|
|
```
|
|
|
|
**5. Docker Engine und Compose installieren**
|
|
|
|
```bash
|
|
sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y
|
|
```
|
|
|
|
**6. Docker aktivieren und testen**
|
|
|
|
```bash
|
|
sudo systemctl enable --now docker
|
|
sudo docker run --rm hello-world
|
|
docker compose version
|
|
```
|
|
|
|
**7. Optional: Docker ohne `sudo` verwenden**
|
|
|
|
```bash
|
|
sudo usermod -aG docker $USER
|
|
```
|
|
|
|
Danach ab- und wieder anmelden.
|
|
|
|
> **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
|
|
```
|
|
|
|
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:
|
|
|
|
<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
|
|
|
|
### 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.
|