Docker: Distribuire con GitHub Actions

Scoprite come distribuire i vostri container Docker utilizzando GitHub Actions

👋 Benvenuti nella documentazione di Stackhero!

Stackhero offre una soluzione Docker cloud CaaS (Containers as a Service) pronta all'uso che fornisce numerosi vantaggi, tra cui:

Distribuisci facilmente i tuoi container in produzione con un semplice docker-compose up.

Nome di dominio personalizzabile protetto con HTTPS (ad esempio, https://api.tua-azienda.com, https://www.tua-azienda.com, https://backoffice.tua-azienda.com).

Prestazioni ottimali e sicurezza robusta grazie a una VM privata e dedicata.

Aggiornamenti senza sforzo con un solo clic.

Risparmia tempo e semplifica la tua vita: bastano 5 minuti per provare la soluzione di hosting cloud Docker CaaS di Stackhero e distribuire i tuoi container in produzione!

GitHub Actions semplifica l'automazione di attività come la distribuzione dei container Docker sui server di produzione. In questa guida vedrete come configurare GitHub Actions in modo sicuro e affidabile per distribuire i vostri container Docker sia in ambienti di staging che di produzione.

Per questa configurazione, manterrete due branch: staging e production. Ogni volta che effettuerete un push su uno di questi branch, il codice verrà automaticamente distribuito sull'istanza Stackhero corrispondente.

Disporre di un'istanza di staging non è obbligatorio. Potete seguire questa guida utilizzando solo un'istanza di produzione. Tuttavia, per ridurre i rischi e aumentare la sicurezza nelle distribuzioni in produzione, è fortemente consigliato avere sia un'istanza di staging che una di produzione. Si tratta di uno standard di settore e di una best practice che può aiutarvi a evitare molti potenziali problemi.

Prima di iniziare, assicuratevi di avere un account GitHub e un repository che ospiti il vostro codice.

Creazione dei servizi Docker

Accedete al vostro pannello di controllo Stackhero e create due servizi Stackhero, uno per lo staging e uno per la produzione. Per mantenere ordine e ridurre al minimo gli errori, potete rinominare questi servizi in "Staging" e "Production".

Non avete ancora un account Stackhero? Potete crearne uno gratuitamente in soli due minuti e poi configurare i vostri servizi Docker cloud con pochi clic.

Esempio di servizi Docker

Configurare variabili d'ambiente e segreti

Ottenere il nome di dominio e la password dei certificati

Per consentire a GitHub Actions di connettersi al vostro servizio Docker Stackhero, avrete bisogno di due informazioni: il nome di dominio del servizio e la password dei certificati.

Nel pannello di controllo Stackhero, selezionate il vostro servizio Docker "production" e fate clic sul pulsante "Configure".

Ottenere le impostazioni del servizio
Copiate sia il "Domain name" che la "Docker certificates password" per utilizzarli nei passaggi successivi.

Ottenere le impostazioni del servizio

Impostare il nome di dominio e la password dei certificati su GitHub

In GitHub, aprite il vostro progetto.
Andate su Settings > Environments, quindi fate clic su New environment.

Configurazione degli ambienti GitHub
Nel campo Name, inserite "production" e confermate.

Impostazione dell'ambiente
Fate clic sul pulsante No restriction e scegliete Selected branches and tags.

Impostazione delle restrizioni dell'ambiente
Fate clic su Add deployment branch or tag rule, inserite "production" nel campo Name pattern e poi fate clic su Add rule.

Impostazione del branch dell'ambiente Impostazione del branch dell'ambiente
Sotto Environment secrets, fate clic su Add secret.

Aggiungi secret
Per il secret, usate STACKHERO_CERTIFICATES_PASSWORD come nome e incollate la vostra password dei certificati nel campo Value.

Impostazione del secret della password dei certificati
Sotto Environment variables, fate clic su Add variable.

Impostazione delle variabili
Usate STACKHERO_ENDPOINT come nome e incollate l'endpoint del vostro servizio Docker nel campo Value. Potete trovare questo endpoint nel vostro pannello di controllo Stackhero.

Impostazione della variabile endpoint

Se avete personalizzato il nome di dominio del vostro servizio, ricordate di utilizzare il vostro dominio personalizzato invece di <XXXXXX>.stackhero-network.com.

Personalizzare il file di configurazione Docker Compose

Se il file docker-compose.yml si trova già nella root del vostro progetto e non avete bisogno di personalizzazioni, potete saltare questa sezione.

Per impostazione predefinita, GitHub Actions cercherà il file docker-compose.yml nella directory principale del progetto. Se avete bisogno di utilizzare un file diverso o una configurazione personalizzata, potete modificare il comando di deploy. Ad esempio, se utilizzate il nostro boilerplate Node.js e Docker per iniziare, potete creare una nuova variabile d'ambiente chiamata STACKHERO_DEPLOY_COMMAND e impostarla così:

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

Configurare il workflow GitHub Actions

Sul vostro computer locale, posizionatevi nella repository Git e create una cartella chiamata .github/workflows. All'interno di questa cartella, create un file chiamato deploy-to-stackhero.yml con il seguente contenuto:

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

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

on:
  push:
    # These branches trigger the deploy action on push.
    # Be sure to create an environment matching the branch name in GitHub (under Settings > Environments).
    # Then add the secret STACKHERO_CERTIFICATES_PASSWORD and variable STACKHERO_ENDPOINT in that 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:
        # The secret STACKHERO_CERTIFICATES_PASSWORD and the variable STACKHERO_ENDPOINT should be defined in the corresponding branch environment on GitHub.
        certificates_password: ${{ secrets.STACKHERO_CERTIFICATES_PASSWORD }}
        endpoint: ${{ vars.STACKHERO_ENDPOINT }}
        # deployment_command is optional. You can use it if you need to customize the Docker Compose command.
        deployment_command: ${{ vars.STACKHERO_DEPLOY_COMMAND }}

Potete confermare le modifiche con:

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

Per creare un branch di produzione, eseguite:

git checkout -b production

Poi effettuate il push del branch production su GitHub:

git push --set-upstream origin production

Una volta che il codice è stato inviato, GitHub Actions lo distribuirà automaticamente sulla vostra istanza Stackhero di produzione. Potete monitorare l'avanzamento della distribuzione tramite la scheda Actions del vostro progetto GitHub.

GitHub Actions che ha distribuito in produzione

Ecco fatto. Ora siete pronti per distribuire automaticamente il vostro codice in produzione utilizzando GitHub Actions.

Creazione dell'ambiente di staging

La configurazione dell'ambiente di staging segue gli stessi passaggi della produzione. Basta ripetere il processo, ma utilizzando staging invece di production.

Quindi, create un branch di staging eseguendo:

git checkout -b staging

E fate il push del branch staging su GitHub:

git push --set-upstream origin staging

Dopo questo, GitHub Actions distribuirà automaticamente il branch di staging sull'istanza Docker dedicata allo staging.

Utilizzare variabili d'ambiente in docker-compose.yml

Potete definire variabili d'ambiente nel vostro progetto GitHub che saranno accessibili all'interno del file docker-compose.yml. Questo è molto utile se volete distribuire su domini diversi (ad esempio, staging.my-company.com per lo staging e my-company.com per la produzione).

In GitHub, andate su Settings > Environments e create una variabile d'ambiente chiamata WEBSITE_DOMAIN.
Per l'ambiente di staging, impostate WEBSITE_DOMAIN su "staging.my-company.com".
Per l'ambiente di produzione, impostate WEBSITE_DOMAIN su "my-company.com".

Successivamente, aggiornate il file .github/workflows/deploy-to-stackhero.yml per passare la variabile WEBSITE_DOMAIN all'azione GitHub Stackhero:

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

Ora aggiornate il file docker-compose.yml per utilizzare la variabile WEBSITE_DOMAIN invece di un nome di dominio hard-coded:

services:
  test:
    image: nginx
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.test.rule=Host(`${WEBSITE_DOMAIN}`)" # Utilizza la variabile d'ambiente WEBSITE_DOMAIN come nome di dominio.
      - "traefik.http.routers.test.tls.certresolver=letsencrypt"

Approfondimenti

È buona prassi proteggere i branch production e staging per evitare push diretti. Con la protezione dei branch attivata, le modifiche vengono introdotte tramite pull request, che devono essere revisionate e unite da una persona con i permessi adeguati. In questo modo, le funzionalità vengono prima validate sulla piattaforma di staging e poi promosse in produzione solo dopo l'approvazione.

Seguendo questo workflow, garantite sia la sicurezza (solo i membri autorizzati del team possono distribuire su staging e produzione) sia l'affidabilità (testando le nuove funzionalità su una piattaforma di staging prima della distribuzione in produzione).