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:

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:

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:

brew install git

Danach prüfen:

git --version

Git konfigurieren

Beim ersten Einrichten den eigenen Namen und die E-Mail-Adresse für Commits hinterlegen:

git config --global user.name "Vorname Nachname"
git config --global user.email "name@example.com"

Repository klonen

macOS / Linux / WSL

cd ~/Documents
git clone https://git.pelpino.de/NAK-Reinickendorf/intranet.git
cd intranet

Windows

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

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

git status
git remote -v

Das Remote Repository sollte auf folgende Adresse verweisen:

https://git.pelpino.de/NAK-Reinickendorf/intranet.git

---

2. Docker installieren

Windows + WSL 2 — empfohlen

PowerShell als Administrator:

wsl --install -d Ubuntu-24.04
wsl --update

Windows neu starten und prüfen:

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:

Settings → Resources → WSL Integration

Integration für Ubuntu aktivieren und in WSL testen:

docker --version
docker compose version
docker run --rm hello-world

Falls docker run mit

permission denied while trying to connect to the docker API at unix:///var/run/docker.sock

abbricht, zunächst prüfen:

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:

newgrp docker

ausführen oder WSL vollständig neu starten. Dazu in 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

sudo apt remove docker.io docker-compose docker-compose-v2 docker-doc docker-buildx podman-docker containerd runc

2. Voraussetzungen installieren

sudo apt update
sudo apt install ca-certificates curl -y

3. Docker GPG-Key hinzufügen

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

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

sudo apt install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin -y

6. Docker aktivieren und testen

sudo systemctl enable --now docker
sudo docker run --rm hello-world
docker compose version

7. Optional: Docker ohne sudo verwenden

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:

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:

Dockerfile
docker-compose.yml
docker-compose.local.yml
web/
worker/
docker/

Die docker-compose.local.yml bildet die Anwendungsdienste der produktiven docker-compose.yml lokal ab und ergänzt die Datenbank. Lokal werden damit gestartet:

• web
• scheduler
• db (PostgreSQL 18 mit pgvector)

Das externe dokploy-network wird lokal nicht benötigt. Alle drei Container verwenden stattdessen das lokale Compose-Netzwerk app. web und scheduler greifen über DB_HOST=db direkt auf den lokalen PostgreSQL-Container zu.

Der Web-Container ist 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:

/var/lib/postgresql

Nicht verwenden:

/var/lib/postgresql/data

Durch den Bind-Mount

./web → /var/www/html

werden Änderungen an PHP, CSS und JavaScript ohne erneuten Image-Build sichtbar. Laufzeitdaten wie Profilbilder, Aushänge, Scheduler-Zustand und generierte Kalenderdateien liegen weiterhin in lokalen Docker-Volumes.

---

4. Environment-Variablen anlegen

Im Projektroot eine .env anlegen. Werte, die lokal nicht benötigt oder noch nicht bekannt sind, bleiben leer.

# PostgreSQL
DB_HOST=
DB_PORT=5432
DB_NAME=intranet
DB_USER=intranet
DB_PASSWORD=local-dev-password

# Intranet
INTRANET_FQDN=localhost:8080

# SMTP / Benachrichtigungen
SMTP_HOST=
SMTP_PORT=
SMTP_USER=
SMTP_PASSWORD=
ADMIN_EMAIL=
SMS_GATEWAY_URL=

# Dashboard / externe APIs
HA_BASE_URL=
HA_TOKEN=
OPENWEATHER_API_KEY=

# Contentpanel / Aushang-Formatüberführung
OLLAMA_GATEWAY_URL=https://ollama.pelpino.de
OLLAMA_API_KEY=
OLLAMA_AUTH_HEADER=Authorization
OLLAMA_MODEL=qwen3.8:27b
OLLAMA_API_STYLE=openai
OLLAMA_TIMEOUT_SECONDS=600
CONTENTPANEL_JOB_TIMEOUT_SECONDS=3600
OLLAMA_MAX_INPUT_CHARS=45000
OLLAMA_CONTEXT_LENGTH=32768
CONTENTPANEL_MAX_INPUT_PAGES=10
CONTENTPANEL_MAX_RENDERED_PAGES=10
CONTENTPANEL_RENDER_SCALE=3

# CKalender / Scheduler
CKAL_USERNAME=
CKAL_PASSWORD=
CKAL_CALENDAR_URL=
CALENDAR_INTERVAL_SECONDS=60

# Strato-Synchronisation
STRATO_SYNC_ENABLED=false
STRATO_SSH_HOST=
STRATO_SSH_PORT=
STRATO_SSH_USER=
STRATO_REMOTE_PATH=
STRATO_SSH_PRIVATE_KEY=
STRATO_KNOWN_HOSTS=

# Brandschutz
BRANDSCHUTZ_MAIL_ENABLED=false

Funktionen, die einen externen Dienst benötigen, funktionieren erst, wenn die zugehörigen Werte gesetzt sind.

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:

docker compose -f docker-compose.local.yml up -d db

Status prüfen:

docker compose -f docker-compose.local.yml ps

Der Datenbank-Container sollte nach einigen Sekunden den Status healthy anzeigen.

---

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.

In pgAdmin einen neuen Server registrieren:

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.

Hinweis: Soll die lokale Datenbank später vollständig durch einen neuen Dump ersetzt werden, kann das lokale Setup zurückgesetzt werden: 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

docker compose -f docker-compose.local.yml up -d --build

Status prüfen:

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:

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:

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

docker compose -f docker-compose.local.yml ps

Web-Logs anzeigen

docker compose -f docker-compose.local.yml logs -f web

Datenbank-Logs anzeigen

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:

docker compose -f docker-compose.local.yml up -d --build

Stoppen

docker compose -f docker-compose.local.yml down

Die Docker-Volumes bleiben dabei erhalten.

Komplett zurücksetzen

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.