Docker: Despliegue con GitHub Actions

Aprenda a desplegar sus contenedores Docker utilizando GitHub Actions

👋 ¡Bienvenido a la documentación de Stackhero!

Stackhero ofrece una solución Docker cloud CaaS (Containers as a Service) lista para usar que proporciona una serie de beneficios, incluyendo:

Despliega fácilmente tus contenedores en producción con solo un docker-compose up.

Nombre de dominio personalizable asegurado con HTTPS (por ejemplo, https://api.tu-empresa.com, https://www.tu-empresa.com, https://backoffice.tu-empresa.com).

Rendimiento óptimo y seguridad robusta gracias a una VM privada y dedicada.

Actualizaciones sin esfuerzo con solo un clic.

Ahorra tiempo y simplifica tu vida: ¡solo toma 5 minutos probar la solución de alojamiento en la nube Docker CaaS de Stackhero y desplegar tus contenedores en producción!

GitHub Actions facilita la automatización de tareas como el despliegue de sus contenedores Docker en servidores de producción. En esta guía, descubrirá cómo configurar GitHub Actions de forma segura y fiable para desplegar sus contenedores Docker tanto en entornos de staging como de producción.

Para esta configuración, mantendrá dos ramas: staging y production. Cada vez que haga un push de código a cualquiera de estas ramas, se desplegará automáticamente en la instancia de Stackhero correspondiente.

Tener una instancia de staging no es obligatorio. Puede seguir esta guía utilizando solo una instancia de producción. Sin embargo, para reducir riesgos y ganar confianza al desplegar en producción, se recomienda encarecidamente disponer tanto de una instancia de staging como de una de producción. Esto es un estándar en la industria y una buena práctica que le ayudará a evitar muchos problemas potenciales.

Antes de comenzar, asegúrese de tener una cuenta de GitHub y un repositorio que aloje su código.

Creación de los servicios Docker

Comience iniciando sesión en su panel de Stackhero y creando dos servicios Stackhero, uno para staging y otro para producción. Para organizarse mejor y minimizar errores, puede renombrar estos servicios como "Staging" y "Production".

¿Aún no tiene una cuenta de Stackhero? Puede crear una de forma gratuita en solo dos minutos y luego desplegar sus servicios Docker en la nube con solo unos clics.

Ejemplo de servicios Docker

Configurar las variables de entorno y secretos

Obtener el nombre de dominio y la contraseña de los certificados

Para permitir que GitHub Actions se conecte a su servicio Docker de Stackhero, necesitará dos datos: el nombre de dominio de su servicio y la contraseña de los certificados.

En el panel de Stackhero, seleccione su servicio Docker "production" y haga clic en el botón "Configure".

Obtener la configuración del servicio
Copie tanto el "Domain name" como la "Docker certificates password" para usarlos en los siguientes pasos.

Obtener la configuración del servicio

Definir el nombre de dominio y la contraseña de los certificados en GitHub

En GitHub, abra su proyecto.
Vaya a Settings > Environments y haga clic en New environment.

Configuración de entornos en GitHub
En el campo Name, escriba "production" y confirme.

Definir el entorno
Haga clic en el botón No restriction y seleccione Selected branches and tags.

Definir restricciones de entorno
Haga clic en Add deployment branch or tag rule, introduzca "production" en el campo Name pattern y luego haga clic en Add rule.

Definir la rama del entorno Definir la rama del entorno
En Environment secrets, haga clic en Add secret.

Añadir secreto
Para el secreto, utilice STACKHERO_CERTIFICATES_PASSWORD como nombre y pegue su contraseña de certificados en el campo Value.

Definir el secreto de la contraseña de los certificados
En Environment variables, haga clic en Add variable.

Definir variables
Utilice STACKHERO_ENDPOINT como nombre y pegue el endpoint de su servicio Docker en el campo Value. Puede encontrar este endpoint en su panel de Stackhero.

Definir la variable endpoint

Si ha personalizado el nombre de dominio de su servicio, recuerde utilizar su dominio personalizado en lugar de <XXXXXX>.stackhero-network.com.

Personalizar el archivo de configuración Docker Compose

Si el archivo docker-compose.yml ya está en la raíz de su proyecto y no necesita personalizaciones, puede saltarse esta sección.

Por defecto, GitHub Actions buscará el archivo docker-compose.yml en el directorio raíz de su proyecto. Si necesita utilizar un archivo diferente o una configuración distinta, puede ajustar el comando de despliegue. Por ejemplo, si está utilizando nuestro boilerplate de Node.js y Docker para empezar, puede crear una nueva variable de entorno llamada STACKHERO_DEPLOY_COMMAND y establecerla así:

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

Configurar el workflow de GitHub Actions

En su máquina local, acceda a su repositorio Git y cree un directorio llamado .github/workflows. Dentro de este directorio, cree un archivo llamado deploy-to-stackhero.yml con el siguiente contenido:

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

Puede confirmar sus cambios con:

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

Para crear una rama de producción, ejecute:

git checkout -b production

Y luego suba su rama de producción a GitHub:

git push --set-upstream origin production

Una vez que su código esté subido, GitHub Actions lo desplegará automáticamente en su instancia de Stackhero de producción. Puede monitorizar el progreso del despliegue revisando la pestaña Actions en su proyecto de GitHub.

GitHub Actions que ha desplegado en producción

Eso es todo. Ahora tiene configurado el despliegue automático de su código en producción utilizando GitHub Actions.

Creación del entorno de staging

La configuración del entorno de staging sigue los mismos pasos que la de producción. Simplemente repita el proceso, pero utilizando staging en lugar de production.

A continuación, cree una rama de staging ejecutando:

git checkout -b staging

Y suba su rama de staging a GitHub:

git push --set-upstream origin staging

Después de esto, GitHub Actions desplegará automáticamente su rama de staging en la instancia Docker designada para staging.

Uso de variables de entorno en docker-compose.yml

Puede definir variables de entorno en su proyecto de GitHub que estarán disponibles dentro de su archivo docker-compose.yml. Esto es muy útil si desea desplegar en diferentes dominios (por ejemplo, staging.my-company.com para staging y my-company.com para producción).

En GitHub, vaya a Settings > Environments y cree una variable de entorno llamada WEBSITE_DOMAIN.
Para el entorno de staging, establezca WEBSITE_DOMAIN en "staging.my-company.com".
Para el entorno de producción, establezca WEBSITE_DOMAIN en "my-company.com".

A continuación, actualice su archivo .github/workflows/deploy-to-stackhero.yml para pasar la variable WEBSITE_DOMAIN a la acción de Stackhero en GitHub:

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

Ahora, actualice su archivo docker-compose.yml para utilizar la variable WEBSITE_DOMAIN en lugar de un nombre de dominio fijo:

services:
  test:
    image: nginx
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.test.rule=Host(`${WEBSITE_DOMAIN}`)" # Utiliza la variable de entorno WEBSITE_DOMAIN como nombre de dominio.
      - "traefik.http.routers.test.tls.certresolver=letsencrypt"

Más allá

Es recomendable proteger las ramas production y staging para evitar pushes directos. Con la protección de ramas activada, los cambios se introducen mediante pull requests, que deben ser revisadas y fusionadas por alguien con los permisos adecuados. Esto permite validar las funcionalidades primero en la plataforma de staging y solo después promoverlas a producción tras su aprobación.

Siguiendo este flujo de trabajo, se garantiza tanto la seguridad (solo los miembros autorizados del equipo pueden desplegar en staging y producción) como la fiabilidad (al probar nuevas funcionalidades en una plataforma de staging antes de desplegarlas en producción).