Docker-container start niet op je NAS? Zo zoek je de oorzaak
Een container die direct weer stopt, op “restarting” blijft staan of helemaal niet wil starten is meestal terug te brengen tot een paar oorzaken. Begin niet meteen met verwijderen en opnieuw installeren: kijk eerst wat de container zelf meldt.
1. Kijk als eerste naar de logs
De logs vertellen vaak letterlijk waarom een container stopt. Open bij Synology Container Manager, kies de container of het project en bekijk de details en logregels. Let vooral op woorden als permission denied, address already in use, connection refused, no such file, out of memory of foutmeldingen rond een database.
Schrijf de eerste duidelijke foutmelding op. De tientallen regels die daarna volgen zijn vaak alleen een gevolg van die eerste fout.
2. Controleer of de poort al in gebruik is
Twee diensten kunnen niet zomaar dezelfde hostpoort gebruiken. Als bijvoorbeeld een bestaande app al poort 8080 gebruikt en je nieuwe container wil diezelfde poort claimen, kan het project niet goed starten.
Controleer in je Compose-bestand of containerinstellingen welke poort links van de dubbele punt staat. Dat is de poort op je NAS. Verander alleen de hostpoort als de applicatie dat toestaat.
3. Controleer de opslagmappen en volumes
Veel containers bewaren hun instellingen en gegevens buiten de container. Als een pad niet bestaat, verkeerd gespeld is of naar de verkeerde gedeelde map wijst, kan de applicatie meteen stoppen.
Controleer daarom:
- bestaat de map op de NAS echt;
- wijst het Compose-bestand naar de juiste locatie;
- is de map nog gekoppeld na een verhuizing of herstel;
- staat belangrijke data niet alleen in de container zelf.
Een opnieuw gemaakte container is geen probleem zolang de persistente gegevens op de juiste plek blijven staan.
4. Kijk naar de rechten
Een container kan alleen bestanden lezen en schrijven als de gebruikte gebruiker voldoende rechten heeft. Problemen ontstaan vaak nadat een map is verplaatst, een nieuwe gedeelde map is aangemaakt of een PUID/PGID is aangepast.
Bij een melding als permission denied moet je dus niet alleen naar Docker kijken, maar ook naar de rechten op de map op de NAS.
5. Controleer environment variables
Veel toepassingen gebruiken variabelen voor bijvoorbeeld databasewachtwoorden, opslaglocaties, tijdzone of hostnaam. Eén ontbrekende waarde kan voldoende zijn om een container te laten stoppen.
Controleer vooral of:
- een
.env-bestand nog aanwezig is; - variabelen exact dezelfde naam hebben als in de documentatie;
- wachtwoorden geen onbedoelde tekens of spaties bevatten;
- paden nog kloppen na een update.
6. Start niet alleen de losse container als er afhankelijkheden zijn
Apps zoals Immich bestaan uit meerdere onderdelen. De applicatie kan afhankelijk zijn van een database, cache of machine-learningcontainer. Als alleen de hoofdcontainer wordt gestart terwijl de database faalt, blijft de hele toepassing defect.
Gebruik bij een Compose-installatie daarom bij voorkeur het project als geheel. Synology Container Manager kan op de Project-pagina projecten met meerdere containers beheren.
7. Controleer CPU, RAM en vrije opslagruimte
Een container kan ook stoppen omdat de NAS simpelweg tegen zijn grenzen loopt. Kijk naar CPU, geheugen en vrije schijfruimte. Vooral databases, fotobibliotheken en machine learning kunnen tijdelijk veel RAM gebruiken.
Een NAS met nog maar enkele honderden megabytes vrije ruimte kan daarnaast vreemd gedrag vertonen. Houd ook ruimte vrij op het volume waarop Docker-data en databases staan.
8. Werkt de container wel, maar de webpagina niet?
Dan is het probleem mogelijk niet de container zelf. Controleer:
- of je het juiste IP-adres van de NAS gebruikt;
- of de hostpoort klopt;
- of de firewall van de NAS verkeer naar die poort toestaat;
- of een reverse proxy nog naar de juiste interne poort wijst;
- of de container in het verwachte Docker-netwerk zit.
9. Na een update kapot? Vergelijk eerst de release notes
Bij grotere applicaties veranderen soms environment variables, databaseversies of Compose-instellingen. Controleer vóór een herinstallatie de release notes van de toepassing en vergelijk je huidige Compose-bestand met de actuele voorbeeldconfiguratie.
Bij Synology kun je binnen een project de YAML-configuratie bekijken en aanpassen. Dat is vaak veiliger dan een volledig nieuwe installatie naast de bestaande gegevens neerzetten.
10. Gebruik “Clean” niet als eerste oplossing
In Synology Container Manager kan de actie Clean projectonderdelen verwijderen voordat je opnieuw bouwt. Dat is nuttig bij een gecontroleerde herbouw, maar niet iets om blind aan te klikken als je nog niet weet waar de persistente gegevens staan.
Maak bij belangrijke toepassingen eerst een back-up en controleer welke data in bind mounts, volumes en databases staat.
Snelle storingsvolgorde
- Lees de eerste echte foutmelding in de logs.
- Controleer poorten.
- Controleer volumes en paden.
- Controleer maprechten.
- Controleer
.enven andere variabelen. - Controleer database en andere afhankelijke containers.
- Controleer RAM, CPU en vrije opslag.
- Controleer firewall en netwerk als de container wel draait.
- Lees release notes als het probleem na een update begon.
- Maak pas daarna containers opnieuw aan.
Specifiek voor Synology Container Manager
Op de Project-pagina kun je de containers van een project, resourcegebruik en de YAML-configuratie bekijken. Dat maakt het meestal makkelijker om een probleem systematisch te zoeken dan losse containers telkens opnieuw te maken.