Entwickler/Deployments und Variablen

Deployments, Variablen und Logs

Die Beispiele nutzen den Helfer hw und $API aus dem Schnellstart, und $APP ist eine Anwendungs-uuid.

Umgebungsvariablen#

Variablen erreichen deine App zur Laufzeit als Umgebungsvariablen, und beim Build, außer du schaltest das ab.

hw -X PATCH $API/applications/$APP/envs/bulk -d '{"data": [
  {"key": "LOG_LEVEL", "value": "info"},
  {"key": "STRIPE_KEY", "value": "sk_live_…", "is_shown_once": true},
  {"key": "GREETING", "value": "Hello $USER", "is_literal": true}
]}'

• is_shown_once: Der Wert lässt sich nie wieder auslesen, weder in der Konsole noch über die API.
• is_literal: $NAMES im Wert bleiben Text, statt ersetzt zu werden.
• is_multiline: für Werte wie PEM-Schlüssel.
• is_buildtime / is_runtime: wann die Variable verfügbar ist (standardmäßig beides).

Gemeinsame Variablen werden einmal gesetzt und von vielen Apps genutzt: {{team.KEY}}, {{project.KEY}} oder {{environment.KEY}} im Wert einer App-Variable. Verwalte sie mit /team/envs, /projects/{uuid}/envs und /projects/{uuid}/environments/{env}/envs.

Deployen#

hw -X POST $API/applications/$APP/start            # build and start
hw -X POST "$API/applications/$APP/start?force=true" # rebuild without the build cache
hw -X POST $API/applications/$APP/restart          # restart without rebuilding
hw -X POST $API/applications/$APP/stop             # take it offline

start antwortet mit {"message": "Deployment request queued.", "deployment_uuid": "…"}. Ein Deployment durchläuft queued → in_progress → finished oder endet als failed oder cancelled-by-user. Schlägt ein Build fehl, läuft die vorherige Version weiter. Mit eingeschaltetem Health Check (health_check_enabled, health_check_path) übernimmt eine neue Version erst, wenn sie antwortet.

Das SDK hat deployAndWait(appUuid) und deployments.wait(deploymentUuid), die für dich abfragen und mit dem Ende des Build-Logs einen Fehler werfen, wenn ein Deployment fehlschlägt.

Logs#

Build-Logs gehören zum Deployment. logs ist eine JSON-kodierte Liste von Zeilen; als hidden markierte Zeilen sind interne Build-Befehle:

hw $API/deployments/$DEPLOYMENT | jq -r '.logs | fromjson | map(select(.hidden | not) | .output) | .[-50:][]'

Laufzeit-Logs sind die Ausgabe des laufenden Containers (braucht Sensible Daten lesen):

hw "$API/applications/$APP/logs?lines=200&show_timestamps=true" | jq -r .logs

Eine gestoppte App antwortet mit 400 Application is not running. Für CPU und Arbeitsspeicher im Zeitverlauf nutze GET /applications/{uuid}/metrics?minutes=60.

Rollback#

hw $API/applications/$APP/rollback-images | jq        # images you can go back to
hw -X POST $API/applications/$APP/rollback -d '{"tag": ""}'

Ein Rollback deployt ein früheres Image erneut, ohne es neu zu bauen.

Push-Deployments#

Um bei jedem git push zu deployen, nutze eins davon:

• GitHub App (empfohlen für GitHub): Verbinde sie in der Konsole unter Quellen und erstelle dann Apps aus ihren Repositories (POST /applications/private-github-app). Pushes auf den Branch der App deployen automatisch; kein Webhook nötig.
• Repository-Webhook (jedes öffentliche oder per Deploy-Key angebundene Repository auf GitHub, GitLab, Bitbucket oder Gitea): Setze ein Secret in der App und füge dann einen Webhook in deinem Repository hinzu.

SECRET=$(openssl rand -hex 24)
hw -X PATCH $API/applications/$APP -d "{\"manual_webhook_secret_github\": \"$SECRET\"}"

Öffne in GitHub im Repository Settings → Webhooks → Add webhook:

Für die anderen Hoster nutze manual_webhook_secret_gitlab, _bitbucket oder _gitea und die passende URL /webhooks/source/<host>/events/manual. Der Tab Webhooks der App in der Konsole zeigt die URLs ebenfalls. Secrets brauchen mindestens 16 Zeichen. Nur Pushes auf den git_branch der App deployen sie; watch_paths (z. B. "src/**") beschränkt Deployments auf Änderungen in diesen Pfaden.

Aus CI deployen#

Ruf den Deploy-Endpunkt auf, nachdem deine Tests bestanden sind. Ein Token mit nur den Berechtigungen Deploy und Lesen reicht:

curl -fsS -X POST "https://console.app.hostwolf.net/api/v1/deploy?uuid=$APP_UUID" \
  -H "Authorization: Bearer $HOSTWOLF_APPS_TOKEN"

Speichere das Token in GitHub Actions als Repository-Secret:

# .github/workflows/deploy.yml
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Deploy to Hostwolf Apps
        run: |
          curl -fsS -X POST "https://console.app.hostwolf.net/api/v1/deploy?uuid=${{ vars.HOSTWOLF_APP }}" \
            -H "Authorization: Bearer ${{ secrets.HOSTWOLF_APPS_TOKEN }}"

Um ein Image zu deployen, das deine Pipeline schon gebaut hat, erstelle die App aus diesem Image (POST /applications/dockerimage) und übergib docker_tag an /deploy.