Elk Docker-image draaien met Container App

Container App draait elk image dat je uit een registry kunt halen: een Node- of Next.js-server, een Python-API, een Go-binary of een tool die nog niemand voor de catalogus heeft verpakt. Jij geeft een image en een poort op; het platform regelt het adres, het TLS-certificaat en de herstarts. Deze handleiding deployt eerst een openbaar image zodat je de hele flow ziet, en behandelt daarna wat je eigen image nodig heeft.

Wat je nodig hebt

• Een Headpat Space-account met een geverifieerd e-mailadres en ingevulde factuurgegevens.
• Een image in een registry zoals Docker Hub of GitHub Container Registry. Heb je alleen broncode, dan kan Container App die voor je bouwen: kies in stap 1 Code uploaden of Vanaf GitHub in plaats van Directe image. Deze handleiding houdt het bij images.

1. Bestel een Container App

1. Log in op het paneel, open Apps in de zijbalk en klik op App aanmaken.
2. Zoek onder Template naar Container App en selecteer het.
3. Kies onder Pakket een pakket en stel de CPU en het geheugen in die je image nodig heeft. Beide kun je later aanpassen.
4. Vul onder Details een Weergavenaam in.
5. Laat onder App-bron de optie Directe image geselecteerd en vul in:
   • Container-image: de volledige verwijzing, inclusief registry en tag. Gebruik voor een eerste test docker.io/nginxinc/nginx-unprivileged:1.27.
   • Container-poort: de poort waarop je app in de container luistert. Voor het testimage is dat 8080.
   • Laat Startcommando en Argumenten leeg, tenzij het image ze nodig heeft.
   • Laat Permanente opslag leeg voor het testimage; stap 2 legt uit wanneer je het invult.
6. Vink het vakje aan waarmee je bevestigt dat de levering direct mag beginnen, klik op App deployen en rond de betaling af.

Het image wordt opgehaald en gestart. Op de app-pagina toont de kaart Toegang het adres van je app. Wacht tot daar HTTPS actief staat en klik dan op Openen. Met het testimage zie je de welkomstpagina van nginx over HTTPS, op een adres dat vanaf nu van jou is.

2. Zet je eigen image erin

Open de kaart Configuratie op de app-pagina. Die heeft dezelfde velden als het bestelformulier: Container-image, Container-poort, Startcommando, Argumenten, Omgevingsvariabelen en Inloggegevens privé-register. Pas aan wat je wilt en klik op Toepassen & herdeployen. De app herstart met de nieuwe instellingen en houdt zijn adres.

Controleer vier dingen voordat je naar je eigen image wijst. Ze veroorzaken vrijwel elke mislukte eerste deploy.

Het moet als non-root draaien

Containers starten hier als gewone gebruiker, en een image dat root wil zijn wordt geweigerd. Je Dockerfile heeft een USER-regel nodig, en de mappen waarin het proces schrijft moeten van die gebruiker zijn. De meeste taal-base-images en goed onderhouden tools doen dit al. Sommige populaire officiële images niet: nginx, httpd en caddy starten als root, en daarom gebruikt de test hierboven nginx-unprivileged. Blijft je app op 0/1 gereed staan op de kaart Status en komt hij nooit bij HTTPS actief, controleer dit dan als eerste; de kaart Logs & diagnose op de app-pagina noemt de reden.

Het moet op alle interfaces luisteren, op poort 1024 of hoger

Bind aan 0.0.0.0, niet aan 127.0.0.1 of localhost; een server die alleen op localhost luistert, is van buiten de container niet bereikbaar. Poorten onder 1024 vereisen root, gebruik dus iets als 3000 of 8080 en vul datzelfde nummer in bij Container-poort. Het platform controleert die poort met een gewone TCP-verbinding: zodra je app verbindingen accepteert, is hij gereed en komt het verkeer binnen.

Het moet gebouwd zijn voor linux/amd64

Onze servers zijn x86-64. Op een Mac met Apple Silicon maakt docker build standaard een arm64-image, en dat start hier niet. Bouw met docker build --platform linux/amd64 -t ghcr.io/jij/app:1.0 . of push een multi-platform-image.

Geef het een volume als het gegevens op schijf bewaart

Een Container App heeft geen eigen schijf, tenzij je er een geeft. Vul bij Permanente opslag de map in waarin je app schrijft, bijvoorbeeld /data: die map behoudt zijn inhoud bij herstarts en herdeploys en zit in de back-ups van de app. Alles daarbuiten is weg zodra de app opnieuw wordt gedeployd of herstart, dus behandel de rest van de container als wegwerpbaar. Databases horen nog steeds in een database-app zoals PostgreSQL of MariaDB: zie PostgreSQL-database aanmaken en ermee verbinden. Een app met een volume herstart bij elke herdeploy op zijn plek, reken dus op enkele seconden downtime per release.

3. Configuratie en geheimen

Gebruik Omgevingsvariabelen voor alles wat verschilt tussen je laptop en productie: database-URL's, API-sleutels, de openbare URL van de app. Klik op Variabele toevoegen, vul naam en waarde in en pas toe. Waarden worden op het platform bewaard en bij het starten aan de container meegegeven; ze hoeven nooit in het image.

Moet je framework zijn eigen openbare URL kennen (Next.js, Django en Rails willen dat vaak), kopieer dan het adres van de kaart Toegang naar de bijbehorende variabele.

4. Images in een privé-register

Is je image niet openbaar, plak dan een Docker config-JSON bij Inloggegevens privé-register. De vorm is:

{"auths": {"ghcr.io": {"auth": "BASE64"}}}

BASE64 is gebruikersnaam:token, gecodeerd met base64, bijvoorbeeld echo -n 'jij:ghp_xxx' | base64. Voor Docker Hub is de sleutel https://index.docker.io/v1/. Gebruik een token dat alleen kan pullen, niet je accountwachtwoord. Na het opslaan toont de kaart Configuratie de tekst inloggegevens ingesteld; plak daar een nieuwe JSON om ze te vervangen.

5. Een nieuwe versie uitrollen

1. Bouw en push het nieuwe image onder een nieuwe tag, bijvoorbeeld ghcr.io/jij/app:1.1.
2. Open de kaart Configuratie, wijzig de tag bij Container-image en klik op Toepassen & herdeployen.

Gebruik voor elke release een nieuwe tag. Nog eens naar dezelfde tag pushen haalt het nieuwe image niet betrouwbaar op. Gebruik je toch latest, dan haalt de knop Herstarten bovenaan de app-pagina de nieuwste latest op en herstart de app.

Je eigen domein gebruiken

Een Container App kan je eigen domein dragen, met certificaat. Zie Je eigen domein aan een app koppelen.

Goed om te weten

• De kaart Logs & diagnose op de app-pagina toont wat de container uitvoert en, als hij niet draait, waarom: een mislukte pull, een geweigerde root-gebruiker, een crash met zijn exitcode. Test het image toch eerst lokaal met docker run --rm -p 8080:8080 jouw-image; een probleem dat je op je laptop ziet, los je daar sneller op.
• Er draait één exemplaar tegelijk. Bij een herdeploy wordt de nieuwe container gestart voordat de oude stopt, dus korte herstarts geven zelden downtime, maar je app moet snel starten en netjes afsluiten bij SIGTERM.
• Het geheugen dat je kiest is een harde grens. Een app die daaroverheen groeit, wordt herstart; verhoog in dat geval het geheugen van het pakket.