Docker: Distribuire con GitHub Actions

Scopri come distribuire i tuoi 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 ti consente di automatizzare attività come la distribuzione dei tuoi container Docker su server di produzione. In questa guida, imparerai a configurare GitHub Actions in modo sicuro e affidabile per distribuire i tuoi container Docker sia in ambienti di staging che di produzione.

Per questa configurazione, manterrai due branch: staging e production. Il codice inviato a ciascun branch verrà automaticamente distribuito all'istanza corrispondente di Stackhero.

Avere un'istanza di staging non è obbligatorio. Puoi seguire questa guida utilizzando solo un'istanza di produzione. Tuttavia, per ridurre i rischi e aumentare la fiducia durante la distribuzione in produzione, è fortemente consigliato avere sia un'istanza di staging che di produzione. Questo è uno standard del settore e una buona pratica che può aiutarti a evitare molti problemi potenziali.

Prima di iniziare, assicurati di avere un account GitHub con un repository che ospita il tuo codice.

Creazione dei servizi Docker

Inizia accedendo alla tua dashboard di Stackhero e creando due servizi Stackhero: uno per lo staging e uno per la produzione. Per minimizzare gli errori, puoi rinominare questi servizi in "Staging" e "Production".

Non hai ancora un account Stackhero? Puoi crearne uno gratuitamente in soli due minuti e poi creare i tuoi servizi cloud Docker con pochi clic.

Esempio di servizi Docker

Configurare le variabili d'ambiente e i segreti

Ottieni il nome di dominio e la password dei certificati

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

Nella dashboard di Stackhero, seleziona il tuo servizio Docker "production" e fai clic sul pulsante "Configure".

Ottieni le impostazioni del servizio
Copia il "Domain name" e la "Docker certificates password" per utilizzarli nei passaggi successivi.

Ottieni le impostazioni del servizio

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

Vai su GitHub e seleziona il tuo progetto.
Fai clic su Settings > Environments e poi su New environment.

Configurazione degli ambienti GitHub
Nel campo Name, inserisci "production" e conferma.

Impostazione dell'ambiente
Fai clic sul pulsante No restriction e seleziona Selected branches and tags.

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

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

Aggiungi un segreto
Per il segreto, inserisci STACKHERO_CERTIFICATES_PASSWORD come nome e incolla la tua password dei certificati come Value.

Impostazione del segreto della password dei certificati
Sotto Environment variables, fai clic su Add variable.

Impostazione delle variabili
Inserisci STACKHERO_ENDPOINT come nome e incolla il tuo endpoint del servizio Docker nel campo Value. Puoi trovare questo endpoint nella tua dashboard di Stackhero.

Impostazione della variabile endpoint

Se hai personalizzato il nome di dominio del tuo servizio, usa la versione personalizzata invece di xxxxxx.stackhero-network.com.

Personalizza il file di configurazione Docker Compose

Se il file docker-compose.yml è presente nella radice del tuo progetto e non sono necessarie personalizzazioni, puoi ignorare questa sezione.

Per impostazione predefinita, GitHub Actions si aspetta che il file Docker Compose docker-compose.yml sia nella radice del tuo progetto. Se hai bisogno di utilizzare un file diverso, puoi personalizzare il comando di distribuzione. Ad esempio, se utilizzi il nostro boilerplate di avvio con Node.js e Docker, puoi creare una nuova variabile d'ambiente chiamata STACKHERO_DEPLOY_COMMAND e impostarla come segue:

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 di GitHub Actions

Sul tuo computer locale, naviga nel tuo repository Git e crea una directory chiamata .github/workflows. In questa directory, crea un file chiamato deploy-to-stackhero.yml con il seguente contenuto:

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

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

on:
  push:
    # Questi branch attivano l'azione di distribuzione al push.
    # Assicurati di creare un ambiente corrispondente al nome del branch su GitHub (sotto Settings > Environments).
    # Poi aggiungi il segreto STACKHERO_CERTIFICATES_PASSWORD e la variabile STACKHERO_ENDPOINT in quell'ambiente.
    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:
        # Il segreto STACKHERO_CERTIFICATES_PASSWORD e la variabile STACKHERO_ENDPOINT devono essere definiti nell'ambiente del branch corrispondente su GitHub.
        certificates_password: ${{ secrets.STACKHERO_CERTIFICATES_PASSWORD }}
        endpoint: ${{ vars.STACKHERO_ENDPOINT }}
        # deployment_command è opzionale. Usalo se hai bisogno di personalizzare il comando Docker Compose.
        deployment_command: ${{ vars.STACKHERO_DEPLOY_COMMAND }}

Conferma le tue modifiche eseguendo:

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

Successivamente, crea un branch di produzione eseguendo:

git checkout -b production

Infine, invia il tuo branch di produzione su GitHub:

git push --set-upstream origin production

Una volta inviato, GitHub Actions distribuirà automaticamente il tuo codice alla tua istanza di produzione Stackhero. Puoi monitorare la distribuzione visitando la scheda Actions nel tuo progetto GitHub.

GitHub Actions che ha distribuito in produzione

Congratulazioni! Ora puoi distribuire automaticamente il tuo codice in produzione utilizzando GitHub Actions.

Creazione dell'ambiente di staging

La configurazione dell'ambiente di staging è simile a quella della produzione. Basta ripetere i passaggi sopra, sostituendo production con staging.

Quindi, crea un branch di staging eseguendo:

git checkout -b staging

Invia il tuo branch di staging su GitHub con:

git push --set-upstream origin staging

GitHub Actions distribuirà automaticamente il tuo branch di staging all'istanza Docker designata per lo staging.

Utilizzo delle variabili d'ambiente in docker-compose.yml

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

Su GitHub, vai su Settings > Environments e crea una variabile d'ambiente chiamata WEBSITE_DOMAIN.
Per l'ambiente di staging, imposta WEBSITE_DOMAIN su "staging.my-company.com".
Per l'ambiente di produzione, imposta WEBSITE_DOMAIN su "my-company.com".

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

name: Deploy to Stackhero
description: Distribuire il branch "${{ github.ref_name }}" su 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 }}

Infine, aggiorna il tuo 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"

Andare oltre

È buona pratica proteggere i branch production e staging per evitare push diretti. Con la protezione dei branch attivata, deve essere creata una pull request per il branch staging e poi fusa da qualcuno con le autorizzazioni necessarie. Una volta convalidato sulla piattaforma di staging, lo stesso processo può essere seguito per il branch production.

Questo approccio aiuta a garantire sia la sicurezza (solo i membri autorizzati del team possono distribuire su staging e produzione) sia l'affidabilità (le funzionalità vengono testate su una piattaforma di staging prima della distribuzione in produzione).