Docker: Mit GitHub Actions bereitstellen

Erfahren Sie, wie Sie Ihre Docker-Container mit GitHub Actions bereitstellen

👋 Willkommen in der Stackhero-Dokumentation!

Stackhero bietet eine einsatzbereite Docker Cloud CaaS (Containers as a Service) Lösung, die zahlreiche Vorteile bietet, darunter:

Einfache Bereitstellung Ihrer Container in der Produktion mit nur einem docker-compose up.

Anpassbarer Domainname gesichert mit HTTPS (zum Beispiel, https://api.ihre-firma.com, https://www.ihre-firma.com, https://backoffice.ihre-firma.com).

Optimale Leistung und robuste Sicherheit durch eine private und dedizierte VM.

Mühelose Updates mit nur einem Klick.

Sparen Sie Zeit und vereinfachen Sie Ihr Leben: Es dauert nur 5 Minuten, um die Docker CaaS Cloud Hosting Lösung von Stackhero auszuprobieren und Ihre Container in der Produktion bereitzustellen!

GitHub Actions ermöglicht es Ihnen, Aufgaben wie das Bereitstellen Ihrer Docker-Container auf Produktionsservern einfach zu automatisieren. In dieser Anleitung erfahren Sie, wie Sie GitHub Actions sicher und zuverlässig einrichten, um Ihre Docker-Container sowohl in Staging- als auch in Produktionsumgebungen zu deployen.

Für dieses Setup verwalten Sie zwei Branches: staging und production. Immer wenn Sie Code auf einen dieser Branches pushen, wird automatisch auf die entsprechende Stackhero-Instanz deployed.

Eine Staging-Instanz ist nicht zwingend erforderlich. Sie können dieser Anleitung auch nur mit einer Produktionsinstanz folgen. Um jedoch Risiken zu minimieren und mehr Sicherheit beim Deployment in die Produktion zu gewinnen, wird dringend empfohlen, sowohl eine Staging- als auch eine Produktionsinstanz zu verwenden. Dies ist ein Industriestandard und eine bewährte Praxis, die Ihnen hilft, viele potenzielle Probleme zu vermeiden.

Bevor Sie beginnen, stellen Sie sicher, dass Sie ein GitHub-Konto und ein Repository haben, das Ihren Code enthält.

Erstellen der Docker-Services

Melden Sie sich zunächst in Ihrem Stackhero-Dashboard an und erstellen Sie zwei Stackhero-Services – einen für Staging und einen für Produktion. Um die Übersicht zu behalten und Fehler zu vermeiden, empfiehlt es sich, diese Services in "Staging" und "Production" umzubenennen.

Sie haben noch kein Stackhero-Konto? Sie können in nur zwei Minuten kostenlos eines erstellen und dann Ihre Docker Cloud-Services mit wenigen Klicks einrichten.

Beispiel für Docker-Services

Umgebungsvariablen und Secrets konfigurieren

Domainnamen und Zertifikatspasswort abrufen

Damit GitHub Actions sich mit Ihrem Stackhero Docker-Service verbinden kann, benötigen Sie zwei Informationen: den Domainnamen Ihres Services und das Passwort für die Zertifikate.

Wählen Sie im Stackhero-Dashboard Ihren "production" Docker-Service aus und klicken Sie auf die Schaltfläche "Configure".

Service-Einstellungen abrufen
Kopieren Sie sowohl den "Domain name" als auch das "Docker certificates password" für die nächsten Schritte.

Service-Einstellungen abrufen

Domainnamen und Zertifikatspasswort in GitHub hinterlegen

Öffnen Sie Ihr Projekt in GitHub.
Gehen Sie zu Settings > Environments und klicken Sie auf New environment.

GitHub-Umgebungen konfigurieren
Geben Sie im Feld Name "production" ein und bestätigen Sie.

Umgebung festlegen
Klicken Sie auf die Schaltfläche No restriction und wählen Sie Selected branches and tags.

Umgebungsrestriktionen festlegen
Klicken Sie auf Add deployment branch or tag rule, geben Sie "production" im Feld Name pattern ein und klicken Sie dann auf Add rule.

Umgebungs-Branch festlegen Umgebungs-Branch festlegen
Unter Environment secrets klicken Sie auf Add secret.

Secret hinzufügen
Verwenden Sie für das Secret den Namen STACKHERO_CERTIFICATES_PASSWORD und fügen Sie Ihr Zertifikatspasswort in das Feld Value ein.

Zertifikatspasswort-Secret festlegen
Unter Environment variables klicken Sie auf Add variable.

Variablen festlegen
Verwenden Sie als Namen STACKHERO_ENDPOINT und fügen Sie den Endpoint Ihres Docker-Services in das Feld Value ein. Sie finden diesen Endpoint in Ihrem Stackhero-Dashboard.

Endpoint-Variable festlegen

Wenn Sie den Domainnamen Ihres Services angepasst haben, denken Sie daran, Ihre eigene Domain anstelle von <XXXXXX>.stackhero-network.com zu verwenden.

Docker Compose-Konfigurationsdatei anpassen

Wenn sich die Datei docker-compose.yml bereits im Root-Verzeichnis Ihres Projekts befindet und Sie keine Anpassungen benötigen, können Sie diesen Abschnitt überspringen.

Standardmäßig sucht GitHub Actions nach der Datei docker-compose.yml im Root-Verzeichnis Ihres Projekts. Falls Sie eine andere Datei oder ein anderes Setup verwenden möchten, können Sie den Deployment-Befehl anpassen. Wenn Sie beispielsweise unser Node.js und Docker Getting Started Boilerplate nutzen, können Sie eine neue Umgebungsvariable namens STACKHERO_DEPLOY_COMMAND anlegen und wie folgt setzen:

docker compose --env-file env.list --file docker/docker-compose.yml --file docker/docker-compose.production.yml up --build --remove-orphans -d

GitHub Actions Workflow konfigurieren

Wechseln Sie auf Ihrer lokalen Maschine in Ihr Git-Repository und erstellen Sie ein Verzeichnis namens .github/workflows. Legen Sie darin eine Datei mit dem Namen deploy-to-stackhero.yml und folgendem Inhalt an:

# File: .github/workflows/deploy-to-stackhero.yml

name: Deploy to Stackhero
description: Deploy branch "${{ github.ref_name }}" to Stackhero

on:
  push:
    # Diese Branches lösen die Deploy-Action beim Push aus.
    # Stellen Sie sicher, dass Sie in GitHub (unter Settings > Environments) eine Umgebung mit dem Branch-Namen anlegen.
    # Fügen Sie dann das Secret STACKHERO_CERTIFICATES_PASSWORD und die Variable STACKHERO_ENDPOINT in dieser Umgebung hinzu.
    branches: [ "production", "staging" ]

jobs:
  Deploy:
    environment: ${{ github.ref_name }}
    runs-on: ubuntu-latest
    steps:
    - uses: stackhero-io/github-actions-deploy-docker-containers-to-stackhero@v1
      with:
        # Das Secret STACKHERO_CERTIFICATES_PASSWORD und die Variable STACKHERO_ENDPOINT sollten in der entsprechenden Branch-Umgebung in GitHub definiert sein.
        certificates_password: ${{ secrets.STACKHERO_CERTIFICATES_PASSWORD }}
        endpoint: ${{ vars.STACKHERO_ENDPOINT }}
        # deployment_command ist optional. Sie können es verwenden, wenn Sie den Docker Compose-Befehl anpassen möchten.
        deployment_command: ${{ vars.STACKHERO_DEPLOY_COMMAND }}

Sie können Ihre Änderungen wie folgt committen:

git add -A .
git commit -m "Add GitHub Actions to deploy to Stackhero"

Um einen Production-Branch zu erstellen, führen Sie aus:

git checkout -b production

Und pushen Sie dann Ihren Production-Branch zu GitHub:

git push --set-upstream origin production

Sobald Ihr Code gepusht ist, wird GitHub Actions ihn automatisch auf Ihrer Stackhero-Produktionsinstanz bereitstellen. Den Fortschritt des Deployments können Sie im Tab Actions Ihres GitHub-Projekts verfolgen.

GitHub Actions, die nach Produktion deployed haben

Das war's. Sie sind jetzt bereit, Ihren Code automatisch mit GitHub Actions in die Produktion zu deployen.

Staging-Umgebung erstellen

Das Einrichten der Staging-Umgebung erfolgt nach denselben Schritten wie für die Produktion. Wiederholen Sie einfach den Prozess, verwenden Sie dabei jedoch staging anstelle von production.

Erstellen Sie dann einen Staging-Branch mit:

git checkout -b staging

Und pushen Sie Ihren Staging-Branch zu GitHub:

git push --set-upstream origin staging

Danach wird GitHub Actions Ihren Staging-Branch automatisch auf die dafür vorgesehene Docker-Instanz für Staging deployen.

Umgebungsvariablen in docker-compose.yml verwenden

Sie können in Ihrem GitHub-Projekt Umgebungsvariablen definieren, die innerhalb Ihrer docker-compose.yml-Datei verfügbar sind. Das ist besonders hilfreich, wenn Sie auf verschiedene Domains deployen möchten (z.B. staging.my-company.com für Staging und my-company.com für Produktion).

Gehen Sie in GitHub zu Settings > Environments und erstellen Sie eine Umgebungsvariable mit dem Namen WEBSITE_DOMAIN.
Für die Staging-Umgebung setzen Sie WEBSITE_DOMAIN auf "staging.my-company.com".
Für die Produktionsumgebung setzen Sie WEBSITE_DOMAIN auf "my-company.com".

Anschließend aktualisieren Sie Ihre Datei .github/workflows/deploy-to-stackhero.yml, um die Variable WEBSITE_DOMAIN an die Stackhero GitHub Action zu übergeben:

name: Deploy to Stackhero
description: Deploy branch "${{ github.ref_name }}" to Stackhero

on:
  push:
    branches: [ "production", "staging" ]

jobs:
  Deploy:
    environment: ${{ github.ref_name }}
    runs-on: ubuntu-latest
    steps:
    - uses: stackhero-io/github-actions-deploy-docker-containers-to-stackhero@v1
      with:
        certificates_password: ${{ secrets.STACKHERO_CERTIFICATES_PASSWORD }}
        endpoint: ${{ vars.STACKHERO_ENDPOINT }}
        deployment_command: ${{ vars.STACKHERO_DEPLOY_COMMAND }}
      env:
        WEBSITE_DOMAIN: ${{ vars.WEBSITE_DOMAIN }}

Jetzt aktualisieren Sie Ihre docker-compose.yml, um die Variable WEBSITE_DOMAIN anstelle eines fest codierten Domainnamens zu verwenden:

services:
  test:
    image: nginx
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.test.rule=Host(`${WEBSITE_DOMAIN}`)" # Verwendet die Umgebungsvariable WEBSITE_DOMAIN als Domainnamen.
      - "traefik.http.routers.test.tls.certresolver=letsencrypt"

Weiterführende Hinweise

Es ist ratsam, die Branches production und staging zu schützen, um direkte Pushes zu verhindern. Mit aktiviertem Branch-Schutz werden Änderungen über Pull Requests eingebracht, die von einer berechtigten Person geprüft und gemerged werden müssen. So werden Features zunächst auf der Staging-Plattform validiert und erst nach Freigabe in die Produktion übernommen.

Mit diesem Workflow stellen Sie sowohl die Sicherheit sicher (nur autorisierte Teammitglieder können auf Staging und Produktion deployen) als auch die Zuverlässigkeit (indem neue Features vor dem Produktivgang auf einer Staging-Plattform getestet werden).