Docker: Deployen met GitHub Actions

Leer hoe u uw Docker-containers kunt deployen met GitHub Actions

👋 Welkom bij de documentatie van Stackhero!

Stackhero biedt een kant-en-klare Docker cloud CaaS (Containers as a Service) oplossing die tal van voordelen biedt, waaronder:

Zet eenvoudig uw containers in productie met slechts een docker-compose up.

Aanpasbare domeinnaam beveiligd met HTTPS (bijvoorbeeld, https://api.uw-bedrijf.com, https://www.uw-bedrijf.com, https://backoffice.uw-bedrijf.com).

Optimale prestaties en robuuste beveiliging aangedreven door een privé en toegewijde VM.

Moeiteloze updates met slechts één klik.

Bespaar tijd en vereenvoudig uw leven: het kost slechts 5 minuten om de Docker CaaS cloud hosting oplossing van Stackhero te proberen en uw containers in productie te zetten!

GitHub Actions maakt het eenvoudig om taken te automatiseren, zoals het deployen van uw Docker-containers naar productieomgevingen. In deze handleiding ontdekt u hoe u GitHub Actions veilig en betrouwbaar instelt om uw Docker-containers naar zowel staging- als productieomgevingen te deployen.

Voor deze setup onderhoudt u twee branches: staging en production. Telkens wanneer u code pusht naar een van deze branches, wordt deze automatisch gedeployed naar de juiste Stackhero-instantie.

Het hebben van een staging-instantie is niet verplicht. U kunt deze handleiding ook volgen met alleen een productie-instantie. Toch wordt het sterk aanbevolen om zowel een staging- als een productie-instantie te hebben, om risico's te beperken en met vertrouwen naar productie te kunnen deployen. Dit is een industriestandaard en een best practice die u kan helpen veel potentiële problemen te voorkomen.

Voordat u begint, zorg ervoor dat u een GitHub-account heeft en een repository waarin uw code staat.

Docker-services aanmaken

Log eerst in op uw Stackhero-dashboard en maak twee Stackhero-services aan: één voor staging en één voor productie. Om het overzicht te bewaren en fouten te minimaliseren, kunt u deze services hernoemen naar "Staging" en "Production".

Heeft u nog geen Stackhero-account? U kunt er gratis een aanmaken in slechts twee minuten en vervolgens uw Docker cloud services met een paar klikken opzetten.

Voorbeeld van Docker-services

Omgevingsvariabelen en secrets configureren

Domeinnaam en certificaatwachtwoord ophalen

Om GitHub Actions verbinding te laten maken met uw Stackhero Docker-service, heeft u twee gegevens nodig: de domeinnaam van uw service en het wachtwoord van de certificaten.

Selecteer in het Stackhero-dashboard uw "production" Docker-service en klik op de knop "Configure".

Service-instellingen ophalen
Kopieer zowel de "Domain name" als het "Docker certificates password" voor gebruik in de volgende stappen.

Service-instellingen ophalen

Domeinnaam en certificaatwachtwoord instellen in GitHub

Open uw project in GitHub.
Ga naar Settings > Environments en klik op New environment.

GitHub-omgevingen configureren
Vul in het veld Name "production" in en bevestig.

Omgeving instellen
Klik op de knop No restriction en kies Selected branches and tags.

Omgevingsrestricties instellen
Klik op Add deployment branch or tag rule, vul "production" in bij Name pattern en klik op Add rule.

Omgevingsbranch instellen Omgevingsbranch instellen
Onder Environment secrets, klik op Add secret.

Secret toevoegen
Gebruik voor de secret STACKHERO_CERTIFICATES_PASSWORD als naam en plak uw certificaatwachtwoord in het veld Value.

Certificaatwachtwoord secret instellen
Onder Environment variables, klik op Add variable.

Variabelen instellen
Gebruik STACKHERO_ENDPOINT als naam en plak uw Docker-service endpoint in het veld Value. U vindt deze endpoint in uw Stackhero-dashboard.

Endpoint-variabele instellen

Als u de domeinnaam van uw service heeft aangepast, gebruik dan uw eigen domein in plaats van <XXXXXX>.stackhero-network.com.

Docker Compose-configuratiebestand aanpassen

Als het bestand docker-compose.yml al in de root van uw project staat en u geen aanpassingen nodig heeft, kunt u deze sectie overslaan.

Standaard zoekt GitHub Actions naar het bestand docker-compose.yml in de root van uw project. Als u een ander bestand of een aangepaste setup wilt gebruiken, kunt u het deployment-commando aanpassen. Bijvoorbeeld, als u onze Getting started with Node.js and Docker boilerplate gebruikt, kunt u een nieuwe omgevingsvariabele aanmaken genaamd STACKHERO_DEPLOY_COMMAND en deze instellen op:

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 configureren

Navigeer op uw lokale machine naar uw Git-repository en maak een map aan genaamd .github/workflows. Maak hierin een bestand aan met de naam deploy-to-stackhero.yml met de volgende inhoud:

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

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

on:
  push:
    # Deze branches triggeren de deploy-actie bij een push.
    # Zorg ervoor dat u een environment aanmaakt die overeenkomt met de branchnaam in GitHub (onder Settings > Environments).
    # Voeg vervolgens de secret STACKHERO_CERTIFICATES_PASSWORD en de variabele STACKHERO_ENDPOINT toe aan die environment.
    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:
        # De secret STACKHERO_CERTIFICATES_PASSWORD en de variabele STACKHERO_ENDPOINT moeten gedefinieerd zijn in de bijbehorende branch environment op GitHub.
        certificates_password: ${{ secrets.STACKHERO_CERTIFICATES_PASSWORD }}
        endpoint: ${{ vars.STACKHERO_ENDPOINT }}
        # deployment_command is optioneel. Gebruik deze als u het Docker Compose-commando wilt aanpassen.
        deployment_command: ${{ vars.STACKHERO_DEPLOY_COMMAND }}

U kunt uw wijzigingen committen met:

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

Om een productiebranch aan te maken, voert u uit:

git checkout -b production

En push vervolgens uw productiebranch naar GitHub:

git push --set-upstream origin production

Zodra uw code is gepusht, zal GitHub Actions deze automatisch deployen naar uw productie Stackhero-instantie. U kunt de voortgang van de deployment volgen via het tabblad Actions in uw GitHub-project.

GitHub Actions die naar productie heeft gedeployed

Dat is alles. Uw setup is nu klaar om uw code automatisch naar productie te deployen met GitHub Actions.

De staging-omgeving aanmaken

Het opzetten van de staging-omgeving verloopt volgens dezelfde stappen als de productie-setup. Herhaal simpelweg het proces, maar gebruik staging in plaats van production.

Maak vervolgens een stagingbranch aan met:

git checkout -b staging

En push uw stagingbranch naar GitHub:

git push --set-upstream origin staging

Hierna zal GitHub Actions uw stagingbranch automatisch deployen naar de toegewezen Docker-instantie voor staging.

Omgevingsvariabelen gebruiken in docker-compose.yml

U kunt omgevingsvariabelen definiëren in uw GitHub-project die beschikbaar zijn in uw docker-compose.yml-bestand. Dit is erg handig als u wilt deployen naar verschillende domeinen (bijvoorbeeld staging.my-company.com voor staging en my-company.com voor productie).

Ga in GitHub naar Settings > Environments en maak een omgevingsvariabele aan met de naam WEBSITE_DOMAIN.
Stel voor de staging-omgeving WEBSITE_DOMAIN in op "staging.my-company.com".
Stel voor de productie-omgeving WEBSITE_DOMAIN in op "my-company.com".

Werk vervolgens uw .github/workflows/deploy-to-stackhero.yml-bestand bij om de variabele WEBSITE_DOMAIN door te geven aan de Stackhero GitHub Action:

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 }}

Werk nu uw docker-compose.yml-bestand bij om de variabele WEBSITE_DOMAIN te gebruiken in plaats van een hardcoded domeinnaam:

services:
  test:
    image: nginx
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.test.rule=Host(`${WEBSITE_DOMAIN}`)" # Gebruikt de omgevingsvariabele WEBSITE_DOMAIN als domeinnaam.
      - "traefik.http.routers.test.tls.certresolver=letsencrypt"

Verder gaan

Het is verstandig om de branches production en staging te beschermen om directe pushes te voorkomen. Met branch protection ingeschakeld, worden wijzigingen via pull requests doorgevoerd, die moeten worden beoordeeld en gemerged door iemand met de juiste rechten. Zo worden features eerst gevalideerd op het stagingplatform en pas na goedkeuring naar productie gebracht.

Door deze workflow te volgen, waarborgt u zowel de veiligheid (alleen geautoriseerde teamleden kunnen naar staging en productie deployen) als de betrouwbaarheid (nieuwe features worden eerst getest op een stagingplatform voordat ze naar productie gaan).