Een statische website in een Nginx-container zetten is een van de makkelijkste manieren om iets zelf te hosten. Toch loop je bijna altijd tegen dezelfde twee problemen aan: een 403 Forbidden en een pagina die leeg blijft of vol vreemde tekens staat. Beide zijn goed op te lossen als je weet waar je moet kijken.
De basisopstelling
In een docker-compose.yml koppel je een map met je website aan de map waaruit Nginx bestanden serveert:
services:
web:
image: nginx:alpine
container_name: mijnsite
restart: unless-stopped
ports:
- "8080:80"
volumes:
- ./site:/usr/share/nginx/html:ro
De map ./site moet dan een bestand index.html bevatten.
Probleem 1: 403 Forbidden
Een 403 betekent dat Nginx de map wél vindt, maar niets mag of kan tonen. De drie meest voorkomende oorzaken:
- De volume mount klopt niet. Staat het pad aan de linkerkant fout, dan maakt Docker soms een lege map aan en mount die. Nginx ziet dan een lege map zonder
index.htmlen geeft een 403, omdat een mapindex standaard niet getoond wordt. - Het indexbestand heet anders. Nginx zoekt standaard
index.html. Een bestand datIndex.htmlofhome.htmlheet werkt niet. Op Linux en in containers maakt hoofdletters wel verschil. - Bestandsrechten. De Nginx-gebruiker in de container moet de bestanden kunnen lezen. Op een NAS of server met strikte rechten kan een map onleesbaar zijn voor andere gebruikers.
Zo controleer je wat de container daadwerkelijk ziet:
docker exec -it mijnsite ls -la /usr/share/nginx/html
docker logs mijnsite --tail 50
Is de map leeg, dan zit het probleem in de mount. Controleer het pad, voer docker compose down en docker compose up -d opnieuw uit en bekijk de uitvoer opnieuw. Staan de bestanden er wel, kijk dan in de logs naar meldingen als directory index of ... is forbidden of permission denied. Beide wijzen duidelijk naar de oorzaak.
Probleem 2: lege pagina of rare tekens
Als je pagina laadt maar alleen een wit scherm of tekens als é in plaats van é toont, ligt het aan de tekencodering:
- Sla bestanden op als UTF-8. Sommige editors op Windows slaan standaard op in ANSI. Bij het kopiëren naar de server of het inpakken in een zip kunnen tekens dan stuk gaan.
- Zet een charset-regel in je HTML:
<meta charset="UTF-8">als eerste regel in de<head>. - Gebruik HTML-entiteiten zoals
évoor speciale tekens als je ergens niet zeker bent van de codering. - Kijk of het bestand echt leeg is. Een mislukte upload of kopie geeft soms een bestand van 0 bytes. Dat zie je met
ls -ladirect.
Open ook de ontwikkelaarstools van je browser (F12) en kijk op het tabblad Console en Netwerk. Een 404 op je CSS- of JavaScript-bestand verklaart een pagina die er kaal of leeg uitziet.
Een snelle checklijst
- Staat er een
index.htmlin de gekoppelde map? - Toont
docker exec ... lsdezelfde bestanden als jouw map? - Zijn de bestanden leesbaar voor andere gebruikers?
- Zijn de bestanden als UTF-8 opgeslagen en heeft de HTML een charset-regel?
- Laadt de pagina na een harde verversing (Ctrl+F5), zodat een oude cache niet in de weg zit?
Vragen of een fout gevonden?
Staat er iets onduidelijks of onjuists in deze gids, of heb je een aanvulling? Laat het me weten via de contactpagina. Meer uitleg over wat ik bouw lees je op Over mij, en meer gidsen vind je in het overzicht.
Wat niet werkt (en waarom)
chmod 777als oplossing. Je verbergt het probleem en zet je map open voor alles. Een 403 komt meestal door een verkeerde mount of door een ontbrekendindex.html, niet door rechten. Kijk eerst wáár Nginx zoekt, dan pas naar de rechten.- Een los bestand mounten in plaats van een map. Een bind mount naar één bestand breekt zodra je editor het bestand vervangt in plaats van het te overschrijven (dat doen veel editors bij opslaan). Mount de hele map.
- Vergeten dat de container zijn eigen pad heeft. Je mount naar
/usr/share/nginx/html, maar je config wijst naar/var/www. Dan is de map in de container leeg, en een lege map metautoindex offgeeft precies een 403. - Tekens repareren met een editor die zelf verminkt. Een pagina met één verkeerd opgeslagen bestand (Latin-1 in plaats van UTF-8) blijft kapot als je hem opnieuw opslaat zonder de codering te kiezen.
Snel oplossen: symptoom, oorzaak, oplossing
| Symptoom | Meestal de oorzaak | Oplossing |
|---|---|---|
| 403 Forbidden | Geen index.html in de gemounte map, of verkeerd pad in de config | Controleer met docker exec -it <naam> ls -l /usr/share/nginx/html |
| 404 terwijl het bestand bestaat | root of alias wijst naar een ander pad | nginx -T in de container draaien en het pad vergelijken |
| Blanco pagina, geen fout | HTML-bestand leeg of verkeerd gekopieerd | Bestandsgrootte controleren en opnieuw kopiëren |
Rare tekens zoals é | Bestand is UTF-8, maar de browser leest iets anders | charset utf-8; in de server-config en <meta charset> in de HTML |
| 502 Bad Gateway | De upstream-container draait niet of luistert op een andere poort | docker ps controleren en de interne poort in de config nalopen |
Veelgestelde vragen
Waarom werkt het lokaal wel en in Docker niet?
Omdat je lokaal naar een map kijkt die de container niet ziet. De container heeft zijn eigen bestandssysteem; alleen wat je expliciet mount, bestaat erin. Dat is de enige vraag die je hoeft te beantwoorden: staat het bestand op het pad dat Nginx gebruikt, ín de container?
Moet ik Nginx Proxy Manager gebruiken of zelf configureren?
Voor een paar statische sites is een eigen nginx.conf leerzamer en lichter. Wil je HTTPS, subdomeinen en certificaten zonder gedoe, dan is Nginx Proxy Manager een prima keuze. Begin simpel; je kunt later altijd overstappen.
Hoe test ik zonder steeds opnieuw te deployen?
Draai de container met een mount naar je werkmap en pas bestanden live aan. Voor de config zelf geldt: nginx -t in de container als test, en daarna nginx -s reload. Een reload is genoeg, je hoeft niet te herstarten.
Verder lezen
- Docker op een Synology NAS met Portainer – de basis onder deze containers.
- Subdomeinen en zoekmachines – je site vindbaar maken zodra hij werkt.
- Een webapp als Android-APK bouwen – als je statische site klaar is.