Het paneel automatiseren met API-sleutels en de CLI

Alles wat je in het paneel kunt aanklikken, kan ook vanuit een script: je apps opsommen, een nieuwe image uitrollen, logs lezen, DNS-records aanpassen. De sleutel daarvoor is een API-sleutel, en de makkelijkste manier om die te gebruiken is de headpat-opdrachtregel. Deze gids behandelt beide.

Wat je nodig hebt

Een Headpat Space-account met een geverifieerd e-mailadres.
Voor de CLI: een computer met Linux, macOS of Windows. Er is geen runtime te installeren; de CLI is een enkel bestand.

1. Maak een API-sleutel

Log in op het paneel, open API-sleutels in de zijbalk.
Klik op API-sleutel aanmaken.
Geef een Sleutelnaam die zegt waar de sleutel gebruikt wordt, bijvoorbeeld GitHub Actions - shop.
Vink onder Scopes alleen aan wat het script nodig heeft. Scopes zijn gegroepeerd (Apps, VM's, Gameservers, Domeinen, DNS, enzovoort), elk met Read en Write. Read laat een sleutel kijken; Write laat hem aanmaken, wijzigen en verwijderen. Een paar scopes zijn gemarkeerd als Gevaarlijk omdat ze in je diensten zelf reiken, zoals opdrachten uitvoeren in een app of de bestanden ervan bewerken; die moet je expliciet aanzetten.
Beperken tot specifieke resources is optioneel. Kies je bijvoorbeeld één app, dan kan de sleutel geen enkele andere app zien of aanraken, ook al zouden de scopes dat toestaan. Gebruik dit voor deploy-sleutels.
Kies een Vervaltermijn. Sleutels die nooit verlopen vervang je zelf af en toe.
Klik op Sleutel aanmaken. De sleutel wordt precies één keer getoond. Kopieer hem naar je wachtwoordmanager of de secrets van je CI voordat je het venster sluit; daarna is alleen het voorvoegsel nog zichtbaar.

Een sleutel die betaalde diensten mag aanmaken heeft een standaard betaalmethode op je account nodig; anders mislukken die aanroepen met een melding die dat zegt.

2. Installeer de CLI

Op Linux en macOS:

curl -fsSL https://headpat.space/install.sh | sh

Op Windows, in PowerShell:

irm https://headpat.space/install.ps1 | iex

Het script kiest de build voor je systeem, controleert hem tegen de gepubliceerde checksums en installeert headpat in ~/.local/bin (op Windows in %LOCALAPPDATA%\Programs\headpat, dat het aan je PATH toevoegt). Staat ~/.local/bin nog niet in je PATH, dan toont het script de regel die je moet toevoegen. Op Alpine Linux voer je eerst apk add libstdc++ libgcc uit.

Met Node.js 18 of nieuwer kun je de installatie overslaan: npx @headpat/cli apps list draait dezelfde CLI, en npm i -g @headpat/cli installeert hem als headpat.

Wil je zelf installeren, download dan het bestand voor je platform van de nieuwste release. macOS kan een in de browser gedownload bestand bij de eerste start weigeren; sta het toe onder Systeeminstellingen, Privacy en beveiliging.

Log daarna in:

headpat login

De CLI opent het paneel in je browser; via SSH toont hij in plaats daarvan de link. Controleer of de pagina dezelfde code toont als je terminal, vink de rechten aan die de CLI mag gebruiken en klik op Goedkeuren. De CLI krijgt een nieuwe API-sleutel met de naam van je computer en bewaart hem in een configuratiebestand dat alleen jouw gebruiker kan lezen (~/.config/headpat/config.json, of %APPDATA%\headpat\config.json op Windows). Die sleutel verloopt niet; je kunt hem altijd beperken of intrekken onder API-sleutels. Wil je een sleutel uit stap 1 opslaan, voer dan headpat login --paste-key uit. In scripts zet je de omgevingsvariabele HEADPAT_API_KEY; die gaat voor op het bestand.

Met headpat update breng je de CLI later naar de nieuwste versie.

3. Dagelijkse opdrachten

headpat apps list
headpat apps get <app-id>
headpat apps logs <app-id> --tail 200
headpat apps restart <app-id>
headpat apps db query <app-id> "select count(*) from orders"
headpat dns records <zone-id>
headpat dns set-record <zone-id> www.example.com A --content 203.0.113.4
headpat vms list
headpat game-servers power <server-id> restart

headpat --help toont alle groepen, headpat apps --help alle opdrachten in een groep en headpat apps create --help de opties van één opdracht. Voeg aan elke opdracht --json toe om het ruwe API-antwoord te krijgen, wat je in scripts wilt:

headpat apps list --json | jq -r '.[] | select(.status != "running") | .displayName'

Wordt een opdracht geweigerd, dan noemt de foutmelding de scope die de sleutel mist, zodat je precies weet wat je moet toevoegen.

4. Een Container App uitrollen vanuit CI

Het meest voorkomende gebruik: een image bouwen in CI en daarna het paneel vertellen die te draaien. Het id van de app staat in de URL in het paneel (de lange code na /apps/).

# .github/workflows/deploy.yml
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
      - uses: docker/build-push-action@v6
        with:
          push: true
          tags: ghcr.io/${{ github.repository }}:${{ github.sha }}
      - name: Install headpat
        run: |
          curl -sL -o headpat https://github.com/HeadpatCloud/headpat-cli/releases/latest/download/headpat-linux-x64
          chmod +x headpat
      - name: Roll out
        env:
          HEADPAT_API_KEY: ${{ secrets.HEADPAT_API_KEY }}
        run: ./headpat apps config ${{ vars.HEADPAT_APP_ID }} --image ghcr.io/${{ github.repository }}:${{ github.sha }}

Voor deze sleutel is Apps: Write, beperkt tot die ene app, genoeg. Het paneel haalt de nieuwe image op en herstart de app; headpat apps status <app-id> toont wanneer hij weer draait. Is de image privé, stel dan eenmalig de registry-gegevens in via de kaart Configuratie van de app in het paneel; de CLI wijzigt alleen de tag.

5. Alles wat verder in de API zit

De CLI heeft opdrachten voor de gangbare taken. De API heeft een paar honderd bewerkingen, gedocumenteerd op api.headpat.space/api/docs. Elke bewerking is op naam aan te roepen:

headpat api apps.sshKeys.list --input '{"appId":"<app-id>"}'
headpat api billing.invoices

Zonder de CLI zijn dezelfde aanroepen gewone HTTPS-verzoeken met de sleutel als bearer-token:

curl -H "Authorization: Bearer $HEADPAT_API_KEY" https://api.headpat.space/api/v1/apps/list

De limieten staan in de header RateLimit-Remaining; scripts die in een lus draaien horen Retry-After bij een 429 te respecteren.

Sleutels veilig houden

Eén sleutel per doel. Een deploy-sleutel die tot één app beperkt is, kan elders geen schade doen als hij lekt.
De kolom Laatst gebruikt op de pagina API-sleutels laat zien of een sleutel nog in gebruik is. Uitschakelen stopt een sleutel meteen zonder hem te verwijderen; Inschakelen zet hem terug aan.
Wijzigingen in scopes gelden bij het volgende verzoek; de sleutel zelf blijft gelijk, dus je kunt een sleutel aanscherpen zonder het script dat hem gebruikt opnieuw uit te rollen.
Zet nooit een sleutel in een repository. Lekt er een, verwijder hem dan in het paneel en maak een nieuwe.