Docker: Implementar com GitHub Actions

Saiba como implementar os seus contentores Docker utilizando o GitHub Actions

👋 Bem-vindo à documentação da Stackhero!

A Stackhero oferece uma solução Docker cloud CaaS (Containers as a Service) pronta a usar que proporciona uma série de benefícios, incluindo:

  • Implemente facilmente os seus containers em produção com apenas um docker-compose up.
  • Nome de domínio personalizável seguro com HTTPS (por exemplo, https://api.sua-empresa.com, https://www.sua-empresa.com, https://backoffice.sua-empresa.com).
  • Desempenho ótimo e segurança robusta alimentados por uma VM privada e dedicada.
  • Atualizações sem esforço com apenas um clique.

Poupe tempo e simplifique a sua vida: são necessários apenas 5 minutos para experimentar a solução de hospedagem cloud Docker CaaS da Stackhero e implementar os seus containers em produção!

O GitHub Actions facilita a automatização de tarefas como a implementação dos seus contentores Docker em servidores de produção. Neste guia, irá descobrir como configurar o GitHub Actions de forma segura e fiável para implementar os seus contentores Docker tanto em ambientes de staging como de produção.

Para esta configuração, irá manter duas branches: staging e production. Sempre que fizer push de código para uma destas branches, a implementação será feita automaticamente na instância Stackhero correspondente.

Ter uma instância de staging não é obrigatório. Pode seguir este guia utilizando apenas uma instância de produção. No entanto, para reduzir riscos e garantir confiança ao implementar em produção, é fortemente recomendado ter tanto uma instância de staging como uma de produção. Esta é uma prática padrão do setor e uma boa prática que pode ajudar a evitar muitos problemas potenciais.

Antes de começar, certifique-se de que tem uma conta GitHub e um repositório que aloje o seu código.

Criar os serviços Docker

Comece por aceder ao seu dashboard Stackhero e criar dois serviços Stackhero, um para staging e outro para produção. Para se organizar melhor e minimizar erros, pode renomear estes serviços para "Staging" e "Production".

Ainda não tem uma conta Stackhero? Pode criar uma gratuitamente em apenas dois minutos e, em seguida, configurar os seus serviços Docker cloud com apenas alguns cliques.

Exemplo de serviços DockerExemplo de serviços Docker

Configurar variáveis de ambiente e segredos

Obter o nome de domínio e a palavra-passe dos certificados

Para permitir que o GitHub Actions se ligue ao seu serviço Docker Stackhero, irá precisar de duas informações: o nome de domínio do seu serviço e a palavra-passe dos certificados.

  1. No dashboard Stackhero, selecione o seu serviço Docker "production" e clique no botão "Configure".

    Obter definições do serviçoObter definições do serviço

  2. Copie tanto o "Domain name" como a "Docker certificates password" para utilizar nos próximos passos.

    Obter definições do serviçoObter definições do serviço

Definir o nome de domínio e a palavra-passe dos certificados no GitHub

  1. No GitHub, abra o seu projeto.

  2. Vá a Settings > Environments e clique em New environment.

    Configurar ambientes no GitHubConfigurar ambientes no GitHub

  3. No campo Name, escreva "production" e confirme.

    Definir o ambienteDefinir o ambiente

  4. Clique no botão No restriction e escolha Selected branches and tags.

    Definir restrições do ambienteDefinir restrições do ambiente

  5. Clique em Add deployment branch or tag rule, introduza "production" no campo Name pattern e depois clique em Add rule.

    Definir branch do ambienteDefinir branch do ambiente Definir branch do ambienteDefinir branch do ambiente

  6. Em Environment secrets, clique em Add secret.

    Adicionar segredoAdicionar segredo

  7. Para o segredo, utilize STACKHERO_CERTIFICATES_PASSWORD como nome e cole a sua palavra-passe dos certificados no campo Value.

    Definir o segredo da palavra-passe dos certificadosDefinir o segredo da palavra-passe dos certificados

  8. Em Environment variables, clique em Add variable.

    Definir variáveisDefinir variáveis

  9. Utilize STACKHERO_ENDPOINT como nome e cole o endpoint do seu serviço Docker no campo Value. Pode encontrar este endpoint no seu dashboard Stackhero.

    Definir variável endpointDefinir variável endpoint

Se personalizou o nome de domínio do seu serviço, lembre-se de utilizar o seu domínio personalizado em vez de <XXXXXX>.stackhero-network.com.

Personalizar o ficheiro de configuração Docker Compose

Se o ficheiro docker-compose.yml já está na raiz do seu projeto e não necessita de personalizações, pode ignorar esta secção.

Por predefinição, o GitHub Actions irá procurar o ficheiro docker-compose.yml na raiz do seu projeto. Se precisar de utilizar um ficheiro diferente ou uma configuração personalizada, pode ajustar o comando de implementação. Por exemplo, se estiver a utilizar o nosso boilerplate de início rápido com Node.js e Docker, pode criar uma nova variável de ambiente chamada STACKHERO_DEPLOY_COMMAND e defini-la como:

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

Configurar o workflow do GitHub Actions

Na sua máquina local, navegue até ao seu repositório Git e crie uma pasta chamada .github/workflows. Dentro desta pasta, crie um ficheiro chamado deploy-to-stackhero.yml com o seguinte conteúdo:

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

Pode confirmar as suas alterações com:

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

Para criar uma branch de produção, execute:

git checkout -b production

E depois faça push da sua branch de produção para o GitHub:

git push --set-upstream origin production

Assim que o seu código for enviado, o GitHub Actions irá implementá-lo automaticamente na sua instância Stackhero de produção. Pode acompanhar o progresso da implementação no separador Actions do seu projeto GitHub.

GitHub Actions que implementou em produçãoGitHub Actions que implementou em produção

E está feito. A sua configuração está agora pronta para implementar automaticamente o seu código em produção utilizando o GitHub Actions.

Criar o ambiente de staging

A configuração do ambiente de staging segue os mesmos passos da configuração de produção. Basta repetir o processo, mas utilizando staging em vez de production.

Depois, crie uma branch de staging executando:

git checkout -b staging

E faça push da sua branch de staging para o GitHub:

git push --set-upstream origin staging

Após isto, o GitHub Actions irá implementar automaticamente a sua branch de staging na instância Docker designada para staging.

Utilizar variáveis de ambiente no docker-compose.yml

Pode definir variáveis de ambiente no seu projeto GitHub que estarão acessíveis dentro do seu ficheiro docker-compose.yml. Isto é muito útil se quiser implementar em domínios diferentes (por exemplo, staging.my-company.com para staging e my-company.com para produção).

  1. No GitHub, vá a Settings > Environments e crie uma variável de ambiente chamada WEBSITE_DOMAIN.
  2. Para o ambiente de staging, defina WEBSITE_DOMAIN como "staging.my-company.com".
  3. Para o ambiente de produção, defina WEBSITE_DOMAIN como "my-company.com".

De seguida, atualize o seu ficheiro .github/workflows/deploy-to-stackhero.yml para passar a variável WEBSITE_DOMAIN para a ação GitHub da 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 }}

Agora, atualize o seu ficheiro docker-compose.yml para utilizar a variável WEBSITE_DOMAIN em vez de um nome de domínio fixo:

services:
  test:
    image: nginx
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.test.rule=Host(`${WEBSITE_DOMAIN}`)" # Utiliza a variável de ambiente WEBSITE_DOMAIN como nome de domínio.
      - "traefik.http.routers.test.tls.certresolver=letsencrypt"

Para além do básico

É aconselhável proteger as branches production e staging para evitar pushes diretos. Com a proteção de branches ativa, as alterações são introduzidas através de pull requests, que devem ser revistas e integradas por alguém com as permissões adequadas. Isto significa que as funcionalidades são primeiro validadas na plataforma de staging e só depois promovidas para produção após aprovação.

Ao seguir este workflow, estará a garantir tanto a segurança (apenas membros autorizados da equipa podem implementar em staging e produção) como a fiabilidade (ao testar novas funcionalidades numa plataforma de staging antes de as colocar em produção).

Outros artigos para Docker

  1. Introdução
    Introdução ao Stackhero para Docker
  2. Introdução
    Como começar com o Stackhero para Docker
  3. Usos avançados de contextos
    Como usar contextos Docker nos seus scripts
  4. Volumes
    Como persistir os dados dos seus containers com volumes Docker
  5. Roteamento HTTPS
    Como gerir o roteamento HTTP e a encriptação TLS (HTTPS) nos seus contentores Docker
  6. Node.js
    Como usar e implementar uma aplicação Node.js com Docker