Installatie van CasaOS-app mislukt: logs, DNS en poorten

Eva Wong is de technisch schrijver en vaste knutselaar bij ZimaSpace. Als levenslange geek met een passie voor homelabs en open-sourcesoftwareis ze gespecialiseerd in het vertalen van complexe technische concepten naar toegankelijke, praktische handleidingen. Eva vindt dat self-hosting leuk moet zijn en niet intimiderend. Met haar tutorials helpt ze de community om hardware-installaties te doorgronden, van het bouwen van hun eerste NAS tot het beheersen van Docker-containers.

Een mislukte installatie van een CasaOS-app levert meestal één eenvoudige foutmelding in de interface op: de appstore wordt niet geladen, de installatieknop van de app werkt niet of de container verschijnt maar wordt nooit geopend. De werkelijke oorzaak ligt meestal dieper dan de CasaOS-interface. CasaOS is ontworpen voor appinstallatie met één klik en implementatie van Docker-apps. Een mislukte installatie kan dus worden veroorzaakt door de servicelaag van CasaOS, het ophalen van Docker-images, DNS-resolutie, systeemtijd, CPU-architectuur of conflicten met hostpoorten.

De veiligste manier om problemen op te lossen is niet om CasaOS meteen opnieuw te installeren. Begin met het bekijken van de daadwerkelijke fout en test vervolgens laag voor laag: logboeken, netwerk en DNS, tijdsynchronisatie, CPU-architectuur, poorten en compatibiliteit met Docker.

Kort gezegd: de foutmelding van CasaOS is slechts het eerste symptoom

Een algemene melding als ‘installatie mislukt’ vertelt je dat CasaOS de implementatie niet kon voltooien, maar niet welke laag de fout veroorzaakte. De appcatalogus is mogelijk niet geladen, Docker heeft de image mogelijk niet opgehaald, de image is mogelijk niet geschikt voor je CPU-architectuur, een hostpoort is mogelijk al bezet of de container is mogelijk gestart en daarna gecrasht.

De installatie van CasaOS-apps is afhankelijk van zowel de servicelaag van CasaOS als de onderliggende Docker-omgeving. Het ophalen van Docker-images kan ook worden beïnvloed door registrytoegang, proxyinstellingen, verbindingen met lage bandbreedte en time-outs bij het downloaden van lagen.

Hanteer deze volgorde:

# 1. CasaOS-servicelogboeken bekijken
journalctl -xeu casaos-app-management --no-pager
journalctl -u casaos -f

# 2. Docker-containers controleren
docker ps -a

# 3. De logboeken van de mislukte container bekijken
docker logs --tail 100 <container_name_or_id>

# 4. DNS en registrytoegang testen
getent hosts github.com
getent hosts registry-1.docker.io

# 5. Systeemtijd controleren
timedatectl

# 6. CPU-architectuur controleren
uname -m

# 7. Luisterende poorten controleren
sudo ss -tulpn | grep LISTEN

Begin met logboeken voordat je instellingen wijzigt

Logboeken zijn de snelste manier om onderscheid te maken tussen een probleem met CasaOS en een probleem met Docker, het netwerk, de image of de app. De Linux-opdracht journalctl toont vermeldingen uit het systemd-logboek en de optie -u filtert logboeken voor een specifieke service-eenheid.

Begin bij CasaOS met logboeken op serviceniveau:

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

Controleer daarna Docker. Met de opdracht docker logs van Docker haal je logboeken van een container op. Met de optie --follow kun je nieuwe uitvoer volgen terwijl de container actief is.

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

Waar je naar zoekt:

Aanwijzing in het logboek Waarschijnlijke oorzaak
no such host / DNS-opzoekfout DNS- of netwerkresolutie
verbinding verlopen Netwerk, proxy, firewall, registrytoegang of lage bandbreedte
certificate / TLS- / x509-fout Systeemtijd, CA-certificaten of HTTPS-onderschepping
fout in uitvoerbaar formaat Verkeerde CPU-architectuur voor de image
port is already allocated / bind: address already in use Conflict met hostpoort
minimaal ondersteunde API-versie API-mismatch tussen Docker-client en -daemon
Container wordt meteen afgesloten Appconfiguratie, volumemachtigingen, ontbrekende omgevingsvariabele of afbeeldingsprobleem

De regel is eenvoudig: probeer niet vijf dingen tegelijk op te lossen. Kopieer de eerste duidelijke foutregel en test vervolgens de laag waar die naar verwijst.

Controleer DNS en netwerktoegang

Als de App Store niet wordt geladen of de installatie mislukt tijdens het downloaden van een image, controleer dan DNS en uitgaand netwerkverkeer voordat je CasaOS-instellingen wijzigt. Docker haalt images op uit registers zoals Docker Hub. Als je CasaOS-host de domeinen van registers niet kan omzetten, kunnen downloads van images mislukken voordat de container zelfs maar is aangemaakt.

Gebruik tests voor naamomzetting in plaats van alleen ping te gebruiken:

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

De opdracht getent raadpleegt databases die zijn geconfigureerd via de Name Service Switch, waaronder de hosts-database die wordt gebruikt om hostnamen op te zoeken. Als deze opdrachten niets teruggeven, kan CasaOS mogelijk geen verbinding maken met GitHub, Docker Hub of een aangepaste appcatalogus, ook al wordt het lokale dashboard nog wel geopend.

Controleer vervolgens de resolverconfiguratie:

cat /etc/resolv.conf

Op Linux is /etc/resolv.conf het configuratiebestand voor de resolver dat voor DNS wordt gebruikt. De vermeldingen nameserver bepalen welke DNS-servers de resolver moet raadplegen. Als DNS niet werkt, kun je tijdelijk overschakelen op stabiele openbare resolvers om te controleren of dit het probleem is:

sudo nano /etc/resolv.conf

Voorbeeld van een tijdelijke test:

nameserver 1.1.1.1
nameserver 8.8.8.8

Neem geen genoegen met “het internet werkt op mijn laptop”. CasaOS draait op de server, dus de DNS-route van de server is van belang.

Controleer de systeemtijd voordat je de App Store de schuld geeft

Een onjuiste systeemtijd kan HTTPS- en certificaatvalidatieproblemen veroorzaken die lijken op problemen met de App Store of het register. Controleer voordat je de Docker- of CasaOS-configuratie wijzigt of de klok van de server goed staat en tijdsynchronisatie actief is.

timedatectl

Zoek in de uitvoer naar regels zoals:

Systeemklok gesynchroniseerd: ja
NTP-service: actief

Schakel dit in als synchronisatie is uitgeschakeld:

sudo timedatectl set-ntp true

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

Controleer of de CPU-architectuur overeenkomt met de app-image

CasaOS kan op verschillende hardwareplatforms draaien, waaronder x86-64- en ARM-apparaten. Dat betekent niet dat elke Docker-app in elke catalogus elke architectuur ondersteunt. Een Raspberry Pi, Orange Pi, kleine ARM-computer of hergebruikte Android-box kan mogelijk geen image uitvoeren die alleen voor linux/amd64 is gebouwd.

Controleer de architectuur van je host:

uname -m
Resultaat van uname -m Gebruikelijke betekenis
x86_64 AMD64 / x86-64
aarch64 ARM64
armv7l 32-bits ARM
i386 / i686 32-bits x86

Containercode moet compatibel zijn met de architectuur van de host, omdat containers de kernel van de host delen. Zonder emulatie kun je geen linux/amd64-container uitvoeren op een arm64-host. Multi-platformimages lossen dit op door varianten zoals linux/amd64 en linux/arm64 onder één image aan te bieden.

Als de logboeken exec format error tonen, controleer dan de imagestatuspagina of het manifest van het register op ARM-ondersteuning. Als de image jouw platform niet ondersteunt, lossen andere CasaOS-instellingen het probleem niet op. Je hebt een image voor meerdere architecturen, een andere tag of een andere app nodig.

Controleer op poortconflicten voordat je opnieuw installeert

Sommige CasaOS-apps worden geïnstalleerd, maar de app wil nog steeds niet openen. Vaak is de container gestart, maar was de hostpoort al in gebruik of onjuist gekoppeld.

Controleer welke poorten actief luisteren:

sudo ss -tulpn | grep LISTEN

Vergelijk het resultaat vervolgens met de poortinstellingen van de app. Docker Compose definieert ports als koppelingen tussen de hostcomputer en containers. Deze koppelingen maken externe toegang tot services in containers mogelijk.

Een typische koppeling ziet er zo uit:

ports:
  - "8080:80"
Onderdeel Betekenis
8080 Hostpoort: wat je in je browser bezoekt
80 Containerpoort: waar de app in de container op luistert

Als een andere service hostpoort 80 al gebruikt, wijzig dan niet eerst de containerpoort. Wijzig de hostpoort in een ongebruikte waarde:

ports:
  - "8080:80"

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

Een praktische checklist voor problemen met CasaOS-apps

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

Controle Opdracht Goed teken Slecht teken
Servicelogboeken van CasaOS journalctl -xeu casaos-app-management --no-pager Duidelijke installatiestroom of specifieke fout Herhaaldelijke servicefout of Docker API-fout
Live logboeken van CasaOS journalctl -u casaos -f UI-acties zijn zichtbaar in de logboeken Actie in de app mislukt zonder melding of blijft zich herhalen
Lijst met Docker-containers docker ps -a Container aangemaakt en status zichtbaar Container ontbreekt of wordt herhaaldelijk opnieuw gestart
Containerlogboeken docker logs --tail 100 <container> App start normaal Afsluit-, machtigings-, configuratie- of architectuurfout
DNS-opzoeking getent hosts registry-1.docker.io IP-adressen geretourneerd Geen resultaat of opzoekfout
Image ophalen docker pull <image>:<tag> Images worden gedownload Time-out, TLS-, authenticatie- of geen overeenkomend manifest
Systeemtijd timedatectl Klok gesynchroniseerd, NTP actief Tijdsverschil of NTP niet actief
Architectuur uname -m Komt overeen met het imageplatform ARM-host met alleen een amd64-image
Poorten sudo ss -tulpn | grep LISTEN Hostpoort niet in gebruik 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 bij normaal appgebruik afhankelijk van externe catalogus- en imagebronnen, dus de server moet deze bronnen kunnen opzoeken en bereiken.

Controleer:

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

Als DNS niet werkt, los dan het probleem met de resolver van de server op. Als DNS wel werkt maar Docker de images niet kan ophalen, test dan de toegang tot het register en controleer de proxy- of firewallinstellingen.

Installatie van de app mislukt tijdens het ophalen van de image

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

docker pull <image>:<tag>

Als het handmatig ophalen mislukt door DNS- of time-outfouten, ligt het probleem niet aan de CasaOS-interface. Als het mislukt door een architectuurfout of omdat er geen overeenkomend manifest is, controleer dan het imageplatform.

App geïnstalleerd, maar kan niet worden geopend

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 de indruk geven dat deze defect is.

Controleer:

docker ps
sudo ss -tulpn | grep LISTEN

Controleer daarna 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>

Let op ontbrekende omgevingsvariabelen, ongeldige volumepaden, databasefouten, machtigingsfouten of exec format error.

Logboeken tonen fouten met de Docker API-versie

Als de logboeken melding maken van incompatibiliteit met de Docker API-versie, ga dan niet gokken. Voer eerst het volgende uit:

docker version

Problemen met Docker API-versies moet je beschouwen als een geavanceerd probleemoplossingsgeval. Overweeg alleen een API-overschrijving als de logboeken duidelijk een API-incompatibiliteit aangeven. Voeg niet zomaar een systemd-overschrijving toe omdat een app één keer niet werkte.

Docker- en machtigingsproblemen in CasaOS-apps

Sommige apps werken niet omdat de container wel is aangemaakt, maar niet de verwachte toegang heeft tot een volume, apparaat of netwerkpad. Dit komt vaak voor wanneer gebruikers aangepaste sjablonen installeren, appgegevens verplaatsen, externe schijven koppelen of handmatig hostmappen wijzigen.

Controleer de gekoppelde paden en logboeken van de app:

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

Let op:

  • hostmap ontbreekt;
  • toegang geweigerd;
  • alleen-lezenbestandssysteem;
  • database kan niet worden geïnitialiseerd;
  • configuratiebestand niet gevonden;
  • apparaatpad ontbreekt;
  • de containergebruiker kan niet naar het gekoppelde volume schrijven.

Als de fout wijst op een probleem met een volume of machtigingen, los dan eerst het pad- of machtigingsprobleem op. Als je de app opnieuw installeert zonder het onjuiste pad te wijzigen, ontstaat meestal dezelfde fout opnieuw.

Fouten die het oplossen van problemen met CasaOS lastiger maken

Fout 1: de app opnieuw installeren voordat je de logboeken leest

Opnieuw installeren kan de oorspronkelijke fout verhullen en dubbele containers, verweesde volumes of herhaaldelijk ophalen van images veroorzaken. Lees eerst de servicelogboeken van CasaOS en de Docker-containerlogboeken.

Fout 2: DNS aanpassen zonder de naamomzetting te testen

Willekeurig DNS-instellingen wijzigen kan het oplossen van problemen lastiger maken. Test eerst de naamomzetting met getent hosts. Als de server domeinen van registers of catalogi niet kan omzetten, pas dan de resolverconfiguratie aan.

Fout 3: compatibiliteit tussen ARM- en AMD64-images negeren

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

Fout 4: containerpoorten wijzigen in plaats van hostpoorten

Als in de documentatie van de app staat dat de container op poort 80 luistert, wijzig dan de interne containerpoort niet, tenzij je weet dat de app dit ondersteunt. Wijzig in plaats daarvan de hostpoort. Zo blijft het interne gedrag van de app intact en voorkom je een conflict op de host.

De installatie veilig opnieuw proberen

Probeer het opnieuw op een gecontroleerde manier nadat je de vermoedelijke oorzaak hebt gevonden:

  1. Noteer de exacte foutmelding.
  2. Los het probleem op in slechts één laag.
  3. Herstart de betreffende service alleen indien nodig.
  4. Probeer de appinstallatie opnieuw.
  5. Houd de logboeken in de gaten terwijl je het opnieuw probeert.
  6. Controleer of de container bestaat.
  7. Controleer of de app-poort luistert.
  8. Open de app via het juiste IP-adres en de juiste hostpoort.

Een veilige nieuwe poging kan er zo uitzien:

journalctl -u casaos -f

In een andere terminal:

docker ps -a
docker logs -f <container_name_or_id>

Probeer de app vervolgens opnieuw in CasaOS. Zo krijg je in één keer de actie in de gebruikersinterface, het gedrag van de CasaOS-service en de uitvoer van de Docker-container te zien.

Veelgestelde vragen

Waarom meldt CasaOS dat de appinstallatie is mislukt?

Omdat er een stap in de installatieketen is mislukt. De oorzaak kan liggen bij CasaOS-servicelogboeken, het ophalen van de Docker-image, DNS, de systeemtijd, de CPU-architectuur, poortconflicten, machtigingen of compatibiliteit met de Docker API. Begin met de logboeken en test vervolgens de stap die wordt aangegeven door de eerste echte foutmelding.

Hoe controleer ik de logboeken van een CasaOS-appinstallatie?

Begin met:

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

Controleer vervolgens Docker:

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

Waarom kan CasaOS de App Store niet laden?

Controleer vooral DNS, uitgaande netwerktoegang, de systeemtijd en de CasaOS-servicelogboeken. Test DNS rechtstreeks op de server met getent hosts github.com en getent hosts registry-1.docker.io en controleer daarna timedatectl en journalctl -u casaos -f.

Wat betekent exec format error in CasaOS?

Dit betekent meestal dat de Docker-image niet overeenkomt met de architectuur van je CPU. Een ARM-host probeert bijvoorbeeld mogelijk een image uit te voeren die alleen voor amd64 geschikt is. Controleer uname -m en ga na of de image je 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 dit vervolgens met de hostpoort van de app. Als een andere service dezelfde hostpoort al gebruikt, wijzig je de hostpoort van de app in een ongebruikte waarde. Laat de containerpoort staan zoals de app die verwacht.

Een mislukte installatie van een CasaOS-app los je veel makkelijker op als je de melding in de gebruikersinterface als een symptoom beschouwt en niet als de oorzaak. Bekijk eerst de logboeken en controleer vervolgens DNS, de tijd, de architectuur, poorten en Docker-compatibiliteit voordat je de app opnieuw installeert of systeembrede instellingen wijzigt.

Ondersteuning en tips

Meer om te lezen

Get More Builds Like This

Stay in the Loop

Get updates from Zima - new products, exclusive deals, and real builds from the community.

Stay in the Loop preferences

We respect your inbox. Unsubscribe anytime.