Docker-Netzwerke und Container-IPs - Versionsgeschichte

Admin am 25. April 2026 um 12:46 Uhr

2026-04-25T12:46:39Z

← Nächstältere Version		Version vom 25. April 2026, 12:46 Uhr
Zeile 49:		Zeile 49:
	Container immer dieselbe IP — unabhängig von der Startreihenfolge:		Container immer dieselbe IP — unabhängig von der Startreihenfolge:

	<~~syntaxhighlight lang="yaml"~~>		<pre>
	services:		services:
	nextcloud:		nextcloud:
Zeile 64:		Zeile 64:
	mein-netzwerk:		mein-netzwerk:
	external: true		external: true
	</~~syntaxhighlight~~>		</pre>

	Docker reserviert diese IPs dauerhaft — kein anderer Container kann sie belegen.		Docker reserviert diese IPs dauerhaft — kein anderer Container kann sie belegen.
Zeile 100:		Zeile 100:
	[[Hairpin-NAT – Collabora und Nextcloud hinter Caddy\|Hairpinning-Problem]].		[[Hairpin-NAT – Collabora und Nextcloud hinter Caddy\|Hairpinning-Problem]].

	<~~syntaxhighlight lang="yaml"~~>		<pre>
	services:		services:
	nextcloud:		nextcloud:
Zeile 111:		Zeile 111:
	# Nextcloud ist intern direkt erreichbar		# Nextcloud ist intern direkt erreichbar
	- "nextcloud.beispiel.de:172.18.0.20"		- "nextcloud.beispiel.de:172.18.0.20"
	</~~syntaxhighlight~~>		</pre>

	=== Warum nicht einfach DNS? ===		=== Warum nicht einfach DNS? ===
Zeile 128:		Zeile 128:
	Der verlässlichste Test ob <code>extra_hosts</code> korrekt greift:		Der verlässlichste Test ob <code>extra_hosts</code> korrekt greift:

	<~~syntaxhighlight lang="bash"~~>		<pre>
	docker exec nextcloud getent hosts collabora.beispiel.de		docker exec nextcloud getent hosts collabora.beispiel.de
	</~~syntaxhighlight~~>		</pre>

	'''Warum <code>getent</code> statt <code>nslookup</code>?'''		'''Warum <code>getent</code> statt <code>nslookup</code>?'''
Zeile 205:		Zeile 205:
	=== 1. IP-Verteilung prüfen ===		=== 1. IP-Verteilung prüfen ===

	<~~syntaxhighlight lang="bash"~~>		<pre>
	docker network inspect NETZWERKNAME \| grep -E "Name\|IPv4"		docker network inspect NETZWERKNAME \| grep -E "Name\|IPv4"
	</~~syntaxhighlight~~>		</pre>

	Alle gepinnten Container müssen ihre festen IPs haben.		Alle gepinnten Container müssen ihre festen IPs haben.
Zeile 213:		Zeile 213:
	=== 2. DNS-Auflösung in den Containern prüfen ===		=== 2. DNS-Auflösung in den Containern prüfen ===

	<~~syntaxhighlight lang="bash"~~>		<pre>
	docker exec nextcloud getent hosts collabora.beispiel.de		docker exec nextcloud getent hosts collabora.beispiel.de
	docker exec collabora getent hosts nextcloud.beispiel.de		docker exec collabora getent hosts nextcloud.beispiel.de
	</~~syntaxhighlight~~>		</pre>

	Beide müssen '''interne''' IPs zurückgeben — nie die externe öffentliche IP.		Beide müssen '''interne''' IPs zurückgeben — nie die externe öffentliche IP.
Zeile 224:		Zeile 224:
	=== 3. Caddy neu starten — nicht nur reload ===		=== 3. Caddy neu starten — nicht nur reload ===

	<~~syntaxhighlight lang="bash"~~>		<pre>
	docker restart caddy		docker restart caddy
	</~~syntaxhighlight~~>		</pre>

	<code>caddy reload</code> übernimmt eine neue Konfiguration manchmal nicht		<code>caddy reload</code> übernimmt eine neue Konfiguration manchmal nicht
Zeile 233:		Zeile 233:
	=== 4. Collabora-Erreichbarkeit aus Nextcloud prüfen ===		=== 4. Collabora-Erreichbarkeit aus Nextcloud prüfen ===

	<~~syntaxhighlight lang="bash"~~>		<pre>
	docker exec nextcloud curl -sk -o /dev/null -w "%{http_code}" \		docker exec nextcloud curl -sk -o /dev/null -w "%{http_code}" \
	https://collabora.beispiel.de/hosting/discovery		https://collabora.beispiel.de/hosting/discovery
	</~~syntaxhighlight~~>		</pre>

	Erwartetes Ergebnis: <code>200</code>		Erwartetes Ergebnis: <code>200</code>
Zeile 247:		Zeile 247:
	=== 5. WOPI-Allowlist prüfen ===		=== 5. WOPI-Allowlist prüfen ===

	<~~syntaxhighlight lang="bash"~~>		<pre>
	docker exec nextcloud occ config:app:get richdocuments wopi_allowlist		docker exec nextcloud occ config:app:get richdocuments wopi_allowlist
	</~~syntaxhighlight~~>		</pre>

	Erwartetes Ergebnis: Das interne Docker-Subnetz, z.B. <code>172.18.0.0/16</code>		Erwartetes Ergebnis: Das interne Docker-Subnetz, z.B. <code>172.18.0.0/16</code>
Zeile 255:		Zeile 255:
	Falls veraltet oder fehlend:		Falls veraltet oder fehlend:

	<~~syntaxhighlight lang="bash"~~>		<pre>
	docker exec nextcloud occ config:app:set richdocuments wopi_allowlist \		docker exec nextcloud occ config:app:set richdocuments wopi_allowlist \
	--value="172.18.0.0/16"		--value="172.18.0.0/16"
	</~~syntaxhighlight~~>		</pre>

	Das gesamte Subnetz statt einer einzelnen IP — damit ist die Allowlist		Das gesamte Subnetz statt einer einzelnen IP — damit ist die Allowlist
Zeile 265:		Zeile 265:
	=== 6. Collabora-Konfiguration aktivieren ===		=== 6. Collabora-Konfiguration aktivieren ===

	<~~syntaxhighlight lang="bash"~~>		<pre>
	docker exec nextcloud occ richdocuments:activate-config		docker exec nextcloud occ richdocuments:activate-config
	</~~syntaxhighlight~~>		</pre>

	Erwartetes Ergebnis:		Erwartetes Ergebnis:

Admin: /* Warum nicht einfach DNS? */

2026-04-24T10:27:18Z

Warum nicht einfach DNS?

← Nächstältere Version		Version vom 24. April 2026, 10:27 Uhr
Zeile 116:		Zeile 116:

	DNS würde die externe IP zurückgeben — der Container würde den Umweg über den		DNS würde die externe IP zurückgeben — der Container würde den Umweg über den
	Router nehmen, der Traffic käme von außen zurück (Hairpinning), und der Resolver		Router nehmen, der Traffic käme von außen zurück ([[Hairpin-NAT – Collabora und Nextcloud hinter Caddy\|Hairpinning]]), und der Resolver
	würde je nach Router-Konfiguration die Verbindung abbrechen.		würde je nach Router-Konfiguration die Verbindung abbrechen.

Admin: Die Seite wurde neu angelegt: „== Docker-Netzwerke und Container-IPs — Konfiguration und Fallstricke == Dieser Artikel erklärt wie Docker IP-Adressen an Container vergibt, warum das nach einem Neustart oder Restore zu Problemen führen kann, und wie man die Konfiguration dauerhaft stabil hält. Er richtet sich an alle die Nextcloud, Collabora, Caddy oder ähnliche Dienste in Docker betreiben und sich fragen warum nach einem Neustart plötzlich nichts mehr funktioniert. ---- == W…“

2026-04-24T10:24:42Z

Die Seite wurde neu angelegt: „== Docker-Netzwerke und Container-IPs — Konfiguration und Fallstricke == Dieser Artikel erklärt wie Docker IP-Adressen an Container vergibt, warum das nach einem Neustart oder Restore zu Problemen führen kann, und wie man die Konfiguration dauerhaft stabil hält. Er richtet sich an alle die Nextcloud, Collabora, Caddy oder ähnliche Dienste in Docker betreiben und sich fragen warum nach einem Neustart plötzlich nichts mehr funktioniert. ---- == W…“

Neue Seite

== Docker-Netzwerke und Container-IPs — Konfiguration und Fallstricke ==

Dieser Artikel erklärt wie Docker IP-Adressen an Container vergibt, warum das nach
einem Neustart oder Restore zu Problemen führen kann, und wie man die Konfiguration
dauerhaft stabil hält.

Er richtet sich an alle die Nextcloud, Collabora, Caddy oder ähnliche Dienste in
Docker betreiben und sich fragen warum nach einem Neustart plötzlich nichts mehr
funktioniert.

----

== Wie Docker IPs vergibt ==

Docker verwaltet ein internes virtuelles Netzwerk. Jeder Container bekommt beim
Start automatisch eine IP-Adresse aus dem konfigurierten Subnetz — standardmäßig
aus <code>172.17.0.0/16</code> oder einem selbst definierten Bereich.

Die Vergabe ist '''dynamisch''': Docker vergibt IPs in der Reihenfolge in der
Container starten. <code>.2</code> geht an den ersten Container, <code>.3</code>
an den zweiten, und so weiter.

Das Problem entsteht nach einem Neustart oder Restore: Container starten in anderer
Reihenfolge, bekommen andere IPs — und alle Konfigurationen die auf feste IPs
angewiesen sind, zeigen ins Leere.

=== Dynamische IP — das stille Problem ===

<pre>
# Vor dem Neustart:
nextcloud → 172.18.0.10
collabora → 172.18.0.4
caddy → 172.18.0.6

# Nach dem Neustart (andere Startreihenfolge):
nextcloud → 172.18.0.7 ← verschoben
collabora → 172.18.0.4 ← zufällig gleich
caddy → 172.18.0.3 ← verschoben
</pre>

Wenn <code>extra_hosts</code> auf die alte Nextcloud-IP zeigt, schlägt WOPI
stillschweigend fehl — kein offensichtlicher Fehler, nur keine Funktion.

----

== Gepinnte IPs — die Lösung ==

Mit <code>ipv4_address</code> in der <code>docker-compose.yml</code> bekommt ein
Container immer dieselbe IP — unabhängig von der Startreihenfolge:

<syntaxhighlight lang="yaml">
services:
nextcloud:
networks:
mein-netzwerk:
ipv4_address: 172.18.0.20

caddy:
networks:
mein-netzwerk:
ipv4_address: 172.18.0.6

networks:
mein-netzwerk:
external: true
</syntaxhighlight>

Docker reserviert diese IPs dauerhaft — kein anderer Container kann sie belegen.

=== Welche Container müssen gepinnt werden? ===

Nicht jeder Container braucht eine feste IP. Gepinnt werden müssen nur Container
die als '''Ziel''' in <code>extra_hosts</code> eines anderen Containers erscheinen:

{| class="wikitable"
! Container !! Gepinnt? !! Grund
|-
| Caddy || '''ja''' || Nextcloud zeigt per <code>extra_hosts</code> auf Caddy
|-
| Nextcloud || '''ja''' || Collabora zeigt per <code>extra_hosts</code> auf Nextcloud. Caddy-Firewall-Regel prüft Nextcloud-IP.
|-
| Collabora || nein || Caddy spricht Collabora über Docker-DNS-Namen an (<code>collabora:9980</code>), nicht über IP
|-
| Datenbank || nein || Wird nur über Docker-DNS-Namen angesprochen
|-
| Redis/Cache || nein || Wird nur über Docker-DNS-Namen angesprochen
|}

'''Faustregel:''' Wer in einem <code>extra_hosts</code>-Eintrag als IP steht, muss
gepinnt sein. Wer nur über seinen Container-Namen angesprochen wird, kann dynamisch
bleiben.

----

== extra_hosts — wann und warum ==

<code>extra_hosts</code> schreibt Einträge direkt in die <code>/etc/hosts</code>
des Containers. Das ist nötig wenn ein Container eine Domain intern auflösen soll,
die extern auf eine andere IP zeigt — das klassische
[[Hairpin-NAT – Collabora und Nextcloud hinter Caddy|Hairpinning-Problem]].

<syntaxhighlight lang="yaml">
services:
nextcloud:
extra_hosts:
# Collabora ist intern über Caddy erreichbar, nicht über die externe IP
- "collabora.beispiel.de:172.18.0.6"

collabora:
extra_hosts:
# Nextcloud ist intern direkt erreichbar
- "nextcloud.beispiel.de:172.18.0.20"
</syntaxhighlight>

=== Warum nicht einfach DNS? ===

DNS würde die externe IP zurückgeben — der Container würde den Umweg über den
Router nehmen, der Traffic käme von außen zurück (Hairpinning), und der Resolver
würde je nach Router-Konfiguration die Verbindung abbrechen.

<code>extra_hosts</code> umgeht DNS komplett: <code>/etc/hosts</code> wird
'''vor''' DNS abgefragt — vor dem Router, vor dem VPN, vor allem anderen.

----

== getent vs. nslookup — warum der Unterschied wichtig ist ==

Der verlässlichste Test ob <code>extra_hosts</code> korrekt greift:

<syntaxhighlight lang="bash">
docker exec nextcloud getent hosts collabora.beispiel.de
</syntaxhighlight>

'''Warum <code>getent</code> statt <code>nslookup</code>?'''

{| class="wikitable"
! !! getent hosts !! nslookup / dig
|-
| Fragt <code>/etc/hosts</code> || '''ja''' || nein
|-
| Fragt <code>extra_hosts</code> || '''ja''' || nein
|-
| Fragt DNS || ja || ja
|-
| Zeigt was der Container wirklich sieht || '''ja''' || nein
|}

<code>getent</code> folgt der NSS-Reihenfolge (<code>/etc/nsswitch.conf</code>) —
genau wie das Betriebssystem selbst. <code>nslookup</code> fragt nur DNS und
ignoriert alle lokalen Overrides. Ein grünes <code>nslookup</code> bedeutet also
nicht dass <code>extra_hosts</code> funktioniert.

=== Die NSS-Reihenfolge ===

Auf einem typischen Linux-System:

<pre>
hosts: files myhostname mdns4_minimal [NOTFOUND=return] dns
</pre>

In einem Docker-Container:

<pre>
hosts: files dns
</pre>

In beiden Fällen: <code>files</code> (also <code>/etc/hosts</code>) kommt zuerst.
Wer dort steht, gewinnt — unabhängig von DNS, VPN oder Router.

----

== IP-Konfiguration dokumentieren ==

Eine gepflegte Übersicht verhindert Verwirrung nach Neustarts oder bei neuen
Containern die zufällig eine reservierte IP belegen würden.

Empfohlenes Format in der eigenen Dokumentation:

{| class="wikitable"
! Container !! IP !! Gepinnt !! Grund
|-
| caddy || 172.18.0.6 || ja || Ziel in Nextcloud extra_hosts
|-
| nextcloud || 172.18.0.20 || ja || Ziel in Collabora extra_hosts; Caddy-Regel prüft diese IP
|-
| collabora || dynamisch || nein || Nur über DNS-Namen angesprochen
|-
| nc-db || dynamisch || nein || Nur über DNS-Namen angesprochen
|-
| nc-redis || dynamisch || nein || Nur über DNS-Namen angesprochen
|}

'''Wichtig:''' Die Tabelle aktuell halten wenn neue Container hinzukommen — ein
neuer Container der dynamisch startet kann eine reservierte IP nicht belegen,
solange die Pinning-Konfiguration in der compose-Datei steht. Aber ein neuer
Container der selbst als Ziel in <code>extra_hosts</code> erscheinen soll,
muss sofort gepinnt werden.

----

== Backup-Restore-Checkliste ==

Nach jedem Backup-Restore in der Reihenfolge abarbeiten:

=== 1. IP-Verteilung prüfen ===

<syntaxhighlight lang="bash">
docker network inspect NETZWERKNAME | grep -E "Name|IPv4"
</syntaxhighlight>

Alle gepinnten Container müssen ihre festen IPs haben.

=== 2. DNS-Auflösung in den Containern prüfen ===

<syntaxhighlight lang="bash">
docker exec nextcloud getent hosts collabora.beispiel.de
docker exec collabora getent hosts nextcloud.beispiel.de
</syntaxhighlight>

Beide müssen '''interne''' IPs zurückgeben — nie die externe öffentliche IP.
Erscheint eine externe IP: <code>extra_hosts</code> greift nicht — die IP in
der <code>docker-compose.yml</code> ist veraltet.

=== 3. Caddy neu starten — nicht nur reload ===

<syntaxhighlight lang="bash">
docker restart caddy
</syntaxhighlight>

<code>caddy reload</code> übernimmt eine neue Konfiguration manchmal nicht
vollständig. Nach einem Restore immer <code>restart</code> verwenden.

=== 4. Collabora-Erreichbarkeit aus Nextcloud prüfen ===

<syntaxhighlight lang="bash">
docker exec nextcloud curl -sk -o /dev/null -w "%{http_code}" \
https://collabora.beispiel.de/hosting/discovery
</syntaxhighlight>

Erwartetes Ergebnis: <code>200</code>

* <code>403</code> → Caddy-Regel blockiert. IP in <code>extra_hosts</code> falsch,
oder Caddy hat alten Stand geladen → Schritt 3 wiederholen.
* Leere Antwort → Nextcloud erreicht Collabora gar nicht →
<code>extra_hosts</code> prüfen (Schritt 2).

=== 5. WOPI-Allowlist prüfen ===

<syntaxhighlight lang="bash">
docker exec nextcloud occ config:app:get richdocuments wopi_allowlist
</syntaxhighlight>

Erwartetes Ergebnis: Das interne Docker-Subnetz, z.B. <code>172.18.0.0/16</code>

Falls veraltet oder fehlend:

<syntaxhighlight lang="bash">
docker exec nextcloud occ config:app:set richdocuments wopi_allowlist \
--value="172.18.0.0/16"
</syntaxhighlight>

Das gesamte Subnetz statt einer einzelnen IP — damit ist die Allowlist
unabhängig von IP-Verschiebungen einzelner Container.

=== 6. Collabora-Konfiguration aktivieren ===

<syntaxhighlight lang="bash">
docker exec nextcloud occ richdocuments:activate-config
</syntaxhighlight>

Erwartetes Ergebnis:

<pre>
✓ Fetched /hosting/discovery endpoint
✓ Valid mimetype response
✓ Valid capabilities entry
✓ Detected WOPI server: Collabora Online ...
</pre>

=== 7. Funktionstest — echtes Dokument öffnen ===

Den Admin-Test in den Nextcloud-Einstellungen '''nicht''' als alleinigen Test
verwenden — er läuft vom Browser aus und bekommt deshalb manchmal <code>403</code>
auch wenn alles korrekt konfiguriert ist.

'''Echter Test:''' Eine <code>.docx</code> oder <code>.odt</code> Datei direkt
in Nextcloud öffnen. Wenn das Dokument im Collabora-Editor erscheint, funktioniert
alles.

----

== Häufige Fehlerquellen ==

{| class="wikitable"
! Symptom !! Ursache !! Fix
|-
| <code>403</code> bei WOPI || <code>extra_hosts</code> zeigt auf falsche IP || IP in <code>docker-compose.yml</code> korrigieren, Container neu starten
|-
| Leere curl-Antwort || Nextcloud erreicht Caddy nicht intern || <code>getent hosts</code> prüfen, <code>extra_hosts</code> korrigieren
|-
| <code>200</code> aber Dokument öffnet nicht || Nextcloud-Cache veraltet || <code>occ richdocuments:activate-config</code> ausführen
|-
| Admin-Test rot, Dokumente gehen || Browser-Referer fehlt || Normal — Admin-Test ist kein verlässlicher Test
|-
| <code>caddy reload</code> hat nichts geändert || Caddy cached alte Konfiguration || <code>docker restart caddy</code> statt <code>caddy reload</code>
|-
| IP-Konflikt beim Container-Start || Anderer Container hat gepinnte IP belegt || <code>docker network inspect</code> → Schuldigen finden → stoppen, neu starten
|}

----

== Siehe auch ==

* [[Hairpin-NAT – Collabora und Nextcloud hinter Caddy]] — das Grundproblem das <code>extra_hosts</code> löst
* [[Caddy – Konzepte und Konfiguration]] — Reverse Proxy, Matcher, Firewall-Regeln
* [[Webserver, Reverse Proxy und Container – wie die Schichten zusammenspielen]]

----

''Entstanden aus einem Debugging-Marathon um 1 Uhr nachts. Möge er anderen erspart bleiben.''

[[Kategorie:Webserver]]
[[Kategorie:Docker]]