NAK-Reinickendorf/intranet
2
0
Fork 0
Code Issues 2 Pull Requests Actions Projects 1 Wiki Activity
Files
5f8a414622222d2f063013fe2f8ac85e3e3f4e91
intranet/README.md
T
leonie 3 ffb5cd336d tutorial fixed
2026-08-27 20:11:57 +02:00

11 KiB
Raw Blame History

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

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

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/

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:

/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 und Aushänge liegen weiterhin in lokalen Docker-Volumes.

4. Environment-Variablen anlegen

Im Projektroot eine .env anlegen:

# 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:

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.

Optional kann geprüft werden, ob pgvector verfügbar ist:

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:

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:

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

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.

Reference in New Issue View Git Blame Copy Permalink