Docker: Deploy with GitHub Actions

Learn how to deploy your Docker containers using GitHub Actions

👋 Welcome to the Stackhero documentation!

Stackhero offers a ready-to-use Docker cloud CaaS (Containers as a Service) solution that provides a host of benefits, including:

  • Easily deploy your containers to production with just a docker-compose up.
  • Customisable domain name secured with HTTPS (for example, https://api.your-company.com, https://www.your-company.com, https://backoffice.your-company.com).
  • Optimal performance and robust security powered by a private and dedicated VM.
  • Effortless updates with just a click.

Save time and simplify your life: it only takes 5 minutes to try Stackhero's Docker CaaS cloud hosting solution and deploy your containers to production!

GitHub Actions allows you to automate tasks such as deploying your Docker containers to production servers. In this guide, you will learn how to set up GitHub Actions securely and reliably to deploy your Docker containers to both staging and production environments.

For this setup, you will maintain two branches: staging and production. Code pushed to each branch will automatically be deployed to the corresponding Stackhero instance.

Having a staging instance is not mandatory. You can follow this guide using only a production instance. However, to reduce risks and build confidence when deploying to production, it is strongly recommended to have both a staging and production instance. This is an industry standard and best practice that can help you avoid many potential issues.

Before you begin, ensure that you have a GitHub account with a repository hosting your code.

Creating the Docker services

Start by logging into your Stackhero dashboard and creating two Stackhero services: one for staging and one for production. To minimise errors, you can rename these services to "Staging" and "Production".

Don't have a Stackhero account yet? You can create one for free in just two minutes and then create your Docker cloud services with only a few clicks.

Example of Docker servicesExample of Docker services

Configure the environment variables and secrets

Get the domain name and certificates password

To allow GitHub Actions to connect to your Stackhero Docker service, you need two pieces of information: the domain name of your service and the certificates password.

  1. In Stackhero's dashboard, select your "production" Docker service and click the "Configure" button.

    Get service settingsGet service settings

  2. Copy the "Domain name" and the "Docker certificates password" for use in the next steps.

    Get service settingsGet service settings

Set the domain name and certificates password in GitHub

  1. Go to GitHub and select your project.

  2. Click on Settings > Environments and then on New environment.

    Configuring GitHub environmentsConfiguring GitHub environments

  3. In the Name field, enter "production" and confirm.

    Setting the environmentSetting the environment

  4. Click the No restriction button and select Selected branches and tags.

    Setting environment restrictionsSetting environment restrictions

  5. Click Add deployment branch or tag rule, enter "production" in the Name pattern field, and then click Add rule.

    Setting environment branchSetting environment branch Setting environment branchSetting environment branch

  6. Under Environment secrets, click Add secret.

    Add secretAdd secret

  7. For the secret, enter STACKHERO_CERTIFICATES_PASSWORD as the name and paste your certificates password as the Value.

    Setting the certificates password secretSetting the certificates password secret

  8. Under Environment variables, click Add variable.

    Setting variablesSetting variables

  9. Enter STACKHERO_ENDPOINT as the name and paste your Docker service endpoint into the Value. You can find this endpoint in your Stackhero dashboard.

    Setting the endpoint variableSetting the endpoint variable

If you have customised your service's domain name, use the customised version instead of xxxxxx.stackhero-network.com.

Customise the Docker Compose configuration file

If the docker-compose.yml file is present at the root of your project and no customisations are needed, you can ignore this section.

By default, GitHub Actions expects the Docker Compose file docker-compose.yml to be in the root of your project. If you need to use a different file, you can customise the deployment command. For example, if you use our Getting started with Node.js and Docker boilerplate, you can create a new environment variable named STACKHERO_DEPLOY_COMMAND and set it to:

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

Configure the GitHub Actions workflow

On your local machine, navigate to your Git repository and create a directory called .github/workflows. In this directory, create a file named deploy-to-stackhero.yml with the following content:

# 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.
    # Ensure you create an environment corresponding to 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. Use it if you need to customise the Docker Compose command.
        deployment_command: ${{ vars.STACKHERO_DEPLOY_COMMAND }}

Commit your changes by running:

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

Next, create a production branch by executing:

git checkout -b production

Finally, push your production branch to GitHub:

git push --set-upstream origin production

Once pushed, GitHub Actions will automatically deploy your code to your production Stackhero instance. You can monitor the deployment by visiting the Actions tab in your GitHub project.

GitHub Actions that deployed to productionGitHub Actions that deployed to production

Congratulations! You can now deploy your code to production automatically using GitHub Actions.

Creating the staging environment

Setting up the staging environment is similar to the production setup. Simply repeat the steps above, replacing production with staging.

Then, create a staging branch by running:

git checkout -b staging

Push your staging branch to GitHub with:

git push --set-upstream origin staging

GitHub Actions will automatically deploy your staging branch to the designated Docker instance for staging.

Using environment variables in docker-compose.yml

You can define environment variables in your GitHub project that will be accessible within your docker-compose.yml file. This is useful if you want to deploy to different domains (for example, staging.my-company.com for staging and my-company.com for production).

  1. On GitHub, go to Settings > Environments and create an environment variable named WEBSITE_DOMAIN.
  2. For the staging environment, set WEBSITE_DOMAIN to "staging.my-company.com".
  3. For the production environment, set WEBSITE_DOMAIN to "my-company.com".

Then, update the .github/workflows/deploy-to-stackhero.yml file to pass the WEBSITE_DOMAIN variable to the 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 }}

Finally, update your docker-compose.yml file to use the WEBSITE_DOMAIN variable instead of a hard-coded domain name:

services:
  test:
    image: nginx
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.test.rule=Host(`${WEBSITE_DOMAIN}`)" # Uses the WEBSITE_DOMAIN environment variable as the domain name.
      - "traefik.http.routers.test.tls.certresolver=letsencrypt"

Going further

It is good practice to protect the production and staging branches to prevent direct pushes. With branch protection enabled, a pull request must be created for the staging branch and then merged by someone with the necessary permissions. Once validated on the staging platform, the same process can be followed for the production branch.

This approach helps ensure both security (only authorised team members can deploy to staging and production) and reliability (features are tested on a staging platform before deployment to production).

Other articles for Docker