CasaOS-appinstallatie mislukt: logs, DNS en poorten

Een mislukte CasaOS-app-installatie ziet er meestal uit als één eenvoudige UI-fout: de app store laadt niet, de knop voor app-installatie werkt niet, of de container verschijnt maar opent nooit. De werkelijke oorzaak ligt meestal dieper dan de CasaOS-interface. CasaOS is ontworpen rond één-klik app-installatie en Docker-app-implementatie, dus een mislukte installatie kan voortkomen uit de CasaOS-servicelaag, het ophalen van Docker-afbeeldingen, DNS-resolutie, systeemtijd, CPU-architectuur of conflicten met hostpoorten.

De veiligste manier om problemen op te lossen is niet om CasaOS eerst opnieuw te installeren. Begin met het lezen van de echte fout, test vervolgens één laag tegelijk: logs, netwerk en DNS, tijdsynchronisatie, CPU-architectuur, poorten en Docker-compatibiliteit.

Kort samengevat: De CasaOS-foutmelding is slechts het eerste symptoom

Een algemene melding “installatie mislukt” geeft aan dat CasaOS de uitrol niet kon voltooien, maar vertelt niet welke laag is mislukt. De app-catalogus is mogelijk niet geladen, Docker heeft de afbeelding mogelijk niet opgehaald, de afbeelding komt mogelijk niet overeen met je CPU-architectuur, een hostpoort is mogelijk al bezet, of de container is gestart en daarna gecrasht.

CasaOS app-installatie is afhankelijk van zowel de CasaOS-servicelaag als de onderliggende Docker-omgeving. Het ophalen van Docker-afbeeldingen kan ook worden beïnvloed door registertoegang, proxy-instellingen, verbindingen met lage bandbreedte en time-outs bij het downloaden van lagen.

Gebruik deze volgorde:

# 1. Lees CasaOS-servicelogs
journalctl -xeu casaos-app-management --no-pager
journalctl -u casaos -f

# 2. Controleer Docker-containers
docker ps -a

# 3. Lees de logs van de mislukte container
docker logs --tail 100 <container_naam_of_id>

# 4. Test DNS- en registertoegang
getent hosts github.com
getent hosts registry-1.docker.io

# 5. Controleer systeemtijd
timedatectl

# 6. Controleer CPU-architectuur
uname -m

# 7. Controleer luisterpoorten
sudo ss -tulpn | grep LISTEN

Begin met logs voordat je instellingen wijzigt

Logs zijn de snelste manier om een CasaOS-probleem te onderscheiden van een Docker-, netwerk-, afbeelding- of app-probleem. De Linux journalctl commando toont vermeldingen uit het systemd-journal, en zijn -u optie filtert logs voor een specifieke service-eenheid.

Voor CasaOS, begin met logs op servicelaag:

journalctl -xeu casaos-app-management --no-pager
journalctl -u casaos -f

Controleer dan Docker. Docker’s docker logs commando haalt logs op van een container, en de --follow optie kan nieuwe uitvoer streamen terwijl de container draait.

docker ps -a
docker logs --tail 100 <container_naam_of_id>
docker logs -f <container_naam_of_id>

Waar je naar op zoek bent:

Log aanwijzing	Waarschijnlijke richting
geen dergelijke host / DNS-zoekfout	DNS- of netwerkresolutie
verbindingstime-out	Netwerk, proxy, firewall, toegang tot register of lage bandbreedte
certificaat / TLS / x509-fout	Systeemtijd, CA-certificaten of HTTPS-interceptie
exec format error	Verkeerde CPU-architectuur voor de afbeelding
poort is al toegewezen / bind: adres is al in gebruik	Conflicterende hostpoort
minimale ondersteunde API-versie	Docker client / daemon API komt niet overeen
Container sluit onmiddellijk af	App-configuratie, volumepermissie, ontbrekende omgevingsvariabele of imageprobleem

De regel is simpel: los niet vijf dingen tegelijk op. Kopieer de eerste duidelijke foutregel en test dan de laag waar deze naar verwijst.

Controleer DNS en netwerktoegang

Als de App Store niet laadt of installatie faalt tijdens het downloaden van een image, controleer dan DNS en uitgaand netwerktoegang voordat je CasaOS-instellingen wijzigt. Docker haalt images op uit registries zoals Docker Hub. Als je CasaOS-host registry-domeinen niet kan resolven, kunnen image-pulls mislukken voordat de container zelfs maar is aangemaakt.

Gebruik naamresolutietests in plaats van alleen ping:

getent hosts github.com
getent hosts registry-1.docker.io
getent hosts hub.docker.com

De getent commando’s raadplegen databases die via de Name Service Switch zijn geconfigureerd, inclusief de hosts-database die wordt gebruikt voor hostnaamopzoekingen. Als deze commando’s niets teruggeven, kan CasaOS mogelijk geen verbinding maken met GitHub, Docker Hub of een aangepaste app-catalogus, zelfs als het lokale dashboard nog wel opent.

Controleer daarna de resolverconfiguratie:

cat /etc/resolv.conf

Op Linux, /etc/resolv.conf is het resolverconfiguratiebestand dat voor DNS wordt gebruikt, en de nameserver vermeldingen definiëren welke DNS-servers de resolver moet raadplegen. Als DNS kapot is, kan tijdelijk overschakelen naar stabiele publieke resolvers bevestigen of dit het probleem is:

sudo nano /etc/resolv.conf

Voorbeeld tijdelijke test:

nameserver 1.1.1.1
nameserver 8.8.8.8

Stop niet bij “het internet werkt op mijn laptop.” CasaOS draait op de server, dus het DNS-pad van de server is wat telt.

Controleer de systeemtijd voordat je de app store de schuld geeft

Onjuiste systeemtijd kan HTTPS en certificaatvalidatie breken op manieren die lijken op fouten in de app store of registry. Controleer voordat je Docker- of CasaOS-configuratie wijzigt of de serverklok correct is en of tijdsynchronisatie actief is.

timedatectl

Zoek in de uitvoer naar regels zoals:

Systeemklok gesynchroniseerd: ja
NTP-service: actief

Als synchronisatie uit staat, schakel deze dan in:

sudo timedatectl set-ntp true

Wacht even na het inschakelen en voer opnieuw uit timedatectl voordat je de installatie van de CasaOS-app opnieuw probeert.

Bevestig dat je CPU-architectuur overeenkomt met het app-image

CasaOS kan draaien op verschillende hardwareplatforms, waaronder x86-64 en ARM-apparaten. Dat betekent niet dat elke Docker-app in elke catalogus elke architectuur ondersteunt. Een Raspberry Pi, Orange Pi, ARM mini board of hergebruikt Android-box kan een image die alleen voor linux/amd64.

Controleer je hostarchitectuur:

uname -m

uname -m resultaat	Gebruikelijke betekenis
x86_64	AMD64 / x86-64
aarch64	ARM64
armv7l	32-bit ARM
i386 / i686	32-bit x86

Containercode moet compatibel zijn met de hostarchitectuur omdat containers de hostkernel delen. Zonder emulatie kun je geen linux/amd64 container op een arm64 host. Multi-platform images lossen dit op door varianten te bieden zoals linux/amd64 en linux/arm64 onder één image.

Als de logs tonen exec format error, controleer de imagepagina of het registry-manifest op ARM-ondersteuning. Als de image jouw platform niet ondersteunt, lost het veranderen van CasaOS-instellingen dit niet op. Je hebt een multi-arch image, een andere tag of een andere app nodig.

Controleer op poortconflicten voordat je opnieuw installeert

Sommige CasaOS app-installaties zijn voltooid, maar de app opent nog steeds niet. In veel gevallen is de container gestart, maar was de hostpoort al bezet of verkeerd toegewezen.

Controleer actieve luisterpoorten:

sudo ss -tulpn | grep LISTEN

Vergelijk het resultaat dan met de poortinstellingen van de app. Docker Compose definieert poorten als mappings tussen de hostmachine en containers, en deze mappings maken externe toegang tot services binnen containers mogelijk.

Een typische mapping ziet er zo uit:

poorten:
  - "8080:80"

Deel	Betekenis
8080	Hostpoort: wat je browser bezoekt
80	Containerpoort: waar de app binnen de container naar luistert

Als een andere service de hostpoort al gebruikt 80, verander eerst niet de containerpoort. Verander de hostpoort naar een ongebruikte waarde:

poorten:
  - "8080:80"

Dit is vooral belangrijk voor apps zoals reverse proxies, adblockers, dashboards en webservers, omdat ze vaak standaard poorten gebruiken 80, 443, 8080, of 3000.

Een praktische CasaOS app-foutchecklist

Gebruik deze checklist voordat je CasaOS opnieuw installeert of containers verwijdert.

Controleer	Commando	Goed teken	Slecht teken
CasaOS servicelogs	journalctl -xeu casaos-app-management --no-pager	Duidelijke installatiestroom of specifieke fout	Herhaalde servicefout of Docker API-fout
CasaOS live logs	journalctl -u casaos -f	UI-acties verschijnen in logs	App-actie faalt stil of blijft hangen
Docker containerlijst	docker ps -a	Container aangemaakt en status zichtbaar	Container ontbreekt of start steeds opnieuw
Containerlogs	docker logs --tail 100 <container>	App start normaal	Exit-, permissie-, configuratie- of architectuurfout
DNS-opzoeking	getent hosts registry-1.docker.io	Geretourneerde IP-adressen	Geen resultaat of opzoekfout
Image-pull	docker pull <image>:<tag>	Image-downloads	Time-out, TLS, authenticatie of geen overeenkomend manifest
Systeemtijd	timedatectl	Klok gesynchroniseerd, NTP actief	Tijdafwijking of NTP inactief
Architectuur	uname -m	Komt overeen met image-platform	ARM-host met alleen amd64-image
Poorten	sudo ss -tulpn | grep LISTEN	Hostpoort ongebruikt	Poort al in gebruik

Veelvoorkomende foutpatronen en wat ze meestal betekenen

App Store laadt niet

Als de App Store zelf niet laadt, begin dan met DNS en netwerktoegang. CasaOS is afhankelijk van externe catalogus- en imagesources tijdens normale app-workflows, dus de server moet deze bronnen kunnen oplossen en bereiken.

Controleer:

getent hosts github.com
getent hosts registry-1.docker.io
timedatectl
journalctl -u casaos -f

Als DNS faalt, repareer dan de serverresolver. Als DNS werkt maar Docker-pulls falen, test dan de toegang tot de registry en proxy- of firewallcondities.

App-installatie mislukt tijdens het ophalen van de image

Als de installatie mislukt tijdens het ophalen van de image, kopieer dan de exacte Docker-fout. Test handmatig:

docker pull <image>:<tag>

Als het handmatig ophalen mislukt met DNS- of time-outfouten, ligt het probleem niet bij de CasaOS UI. Als het mislukt met een architectuurfout of geen overeenkomend manifest, controleer dan het afbeeldingsplatform.

App geïnstalleerd maar kan niet openen

Als de app geïnstalleerd lijkt maar de browser deze niet kan openen, controleer dan eerst de poorten. Een onjuiste of conflicterende hostpoort kan een werkende container kapot laten lijken.

Controleer:

docker ps
sudo ss -tulpn | grep LISTEN

Controleer vervolgens of de app is gekoppeld aan de hostpoort die je bezoekt.

App start en stopt onmiddellijk

Als de container bestaat maar stopt, lees dan de containerlogboeken:

docker logs --tail 100 <container>

Zoek naar ontbrekende omgevingsvariabelen, ongeldige volumepaden, databasefouten, machtigingsfouten of exec format error.

Logboeken tonen Docker API-versiefouten

Als logboeken melding maken van incompatibiliteit van de Docker API-versie, raadpleeg dan niet zomaar. Voer eerst uit:

docker versie

Docker API-versieproblemen moeten als een geavanceerd probleem worden behandeld. Overweeg alleen een API-override als de logboeken duidelijk een API-onverenigbaarheid tonen. Voeg geen systemd-override toe alleen omdat een app één keer is mislukt.

Docker- en machtigingsproblemen in CasaOS-apps

Sommige apps falen omdat de container is gemaakt maar niet de verwachte toegang heeft tot een volume, apparaat of netwerkpad. Dit komt vaak voor wanneer gebruikers aangepaste sjablonen installeren, app-gegevens verplaatsen, externe schijven koppelen of hostmappen handmatig wijzigen.

Controleer de toegewezen paden en logboeken van de app:

docker inspect <container_naam_of_id>
docker logs --tail 100 <container_naam_of_id>

Zoek naar:

• ontbrekende hostmap;
• toegang geweigerd;
• alleen-lezen bestandssysteem;
• database kan niet initialiseren;
• configuratiebestand niet gevonden;
• apparaatpad ontbreekt;
• containergebruiker kan niet schrijven naar aangekoppeld volume.

Als de fout wijst op een volume- of machtigingsprobleem, los dan eerst het pad of de machtiging op. Het herinstalleren van de app zonder het slechte pad te wijzigen, veroorzaakt meestal dezelfde fout opnieuw.

Fouten die het oplossen van problemen met CasaOS bemoeilijken

Fout 1: De app herinstalleren voordat je de logboeken leest

Herinstalleren kan de oorspronkelijke fout verbergen en dubbele containers, verweesde volumes of herhaalde afbeeldingsdownloads veroorzaken. Lees eerst de CasaOS-servicelogboeken en Docker-containerlogboeken.

Fout 2: DNS aanpassen zonder naamresolutie te testen

Het willekeurig wijzigen van DNS kan het oplossen van problemen bemoeilijken. Test eerst de resolutie met getent hosts. Als de server geen registraties of catalogusdomeinen kan oplossen, pas dan de resolverconfiguratie aan.

Fout 3: ARM versus AMD64 afbeeldingscompatibiliteit negeren

CasaOS kan draaien op ARM-apparaten, maar niet elke app-afbeelding ondersteunt ARM. Als je host aarch64 of armv7l en de image is alleen voor amd64, kan de installatie mislukken of kan de container stoppen met exec format error.

Fout 4: Containerpoorten wijzigen in plaats van hostpoorten

Als de app-documentatie zegt dat de container luistert op poort 80wijzig de interne containerpoort niet tenzij je zeker weet dat de app dit ondersteunt. Wijzig in plaats daarvan de hostpoort. Dit houdt het interne servicegedrag van de app intact en voorkomt een conflict op hostniveau.

Hoe de installatie veilig opnieuw te proberen

Nadat je de waarschijnlijke oorzaak hebt gevonden, probeer het dan gecontroleerd opnieuw:

1. Bewaar het exacte foutbericht.
2. Los maar één laag tegelijk op.
3. Herstart alleen de gerelateerde service als dat nodig is.
4. Probeer de app-installatie opnieuw.
5. Bekijk de logs tijdens het opnieuw proberen.
6. Controleer of de container bestaat.
7. Controleer of de app-poort luistert.
8. Open de app vanaf het juiste host-IP en de juiste hostpoort.

Een veilige herstart kan er zo uitzien:

journalctl -u casaos -f

In een ander terminalvenster:

docker ps -a
docker logs -f <container_naam_of_id>

Probeer dan de app opnieuw in CasaOS. Dit geeft je de UI-actie, CasaOS-servicegedrag en Docker-containeruitvoer in één keer.

FAQ

Waarom zegt CasaOS dat de app-installatie is mislukt?

Omdat één laag in de installatiekette is mislukt. De oorzaak kan CasaOS-servicelogs, Docker-image downloaden, DNS, systeemtijd, CPU-architectuur, poortconflicten, permissies of Docker API-compatibiliteit zijn. Begin met logs, test dan de laag die de eerste echte fout toont.

Hoe controleer ik CasaOS-app-installatielogs?

Begin met:

journalctl -xeu casaos-app-management --no-pager
journalctl -u casaos -f

Controleer dan Docker:

docker ps -a
docker logs --tail 100 <container_naam_of_id>

Waarom kan CasaOS de App Store niet laden?

De meest voorkomende controles zijn DNS, uitgaand netwerktoegang, systeemtijd en CasaOS-servicelogs. Test DNS vanaf de server zelf met getent hosts github.com en getent hosts registry-1.docker.io, controleer dan timedatectl en journalctl -u casaos -f.

Wat betekent exec format error betekent in CasaOS?

Dit betekent meestal dat de Docker-image niet overeenkomt met je CPU-architectuur. Bijvoorbeeld, een ARM-host probeert een alleen voor amd64 geschikte image te draaien. Controleer uname -m en bevestig of de image jouw platform ondersteunt.

Hoe weet ik of een CasaOS-app is mislukt door een poortconflict?

Controleer welke poorten al luisteren:

sudo ss -tulpn | grep LISTEN

Vergelijk dat vervolgens met de hostpoort van de app. Als een andere dienst dezelfde hostpoort al gebruikt, wijzig dan de hostpoort van de app naar een ongebruikte waarde terwijl je de containerpoort laat zoals de app verwacht.

Een installatieprobleem met een CasaOS-app wordt veel makkelijker op te lossen als je het UI-bericht als een symptoom ziet, niet als de hoofdoorzaak. Lees eerst de logs, controleer dan DNS, tijd, architectuur, poorten en Docker-compatibiliteit voordat je de app opnieuw installeert of systeeminstellingen wijzigt.