GitHub, DockerHub and StackOS Integration

Using GitHub Actions, you can automate the building of your application and streamline the docker image creation and updating process.

GitHub Actions

Enable Github Actions for your GitHub Repository

Docker Hub Secrets

After logging in to Docker Hub go to: https://hub.docker.com/settings/security

Create a token by clicking "New Access Token"

Give your access token a name and Generate

Retain the following information for configuration into Github Actions 1) Your username and 2) the personal access token

GitHub Secrets

To automatically upload the results of your Docker Image Build to Docker Hub, configure secrets into the target respository. These Docker Hub secrets will be used to upload you image to Docker Hub.

Insert the information from Docker Hub into "Environment secrets" on Github Environments named "docker"

Set up GitHub Workflow

In your repo set up a file named .github/workflows/ci.yaml, and replace the values of "DOCKERHUB_USERNAME" and "DOCKERHUB_IMAGENAME" in the code below

name: ci

on:
  push:
    branches:
      - '**'
    tags:
      - 'v*.*.*'
  pull_request:
    branches:
      - 'main'

jobs:
  docker:
    environment: docker
    runs-on: ubuntu-latest
    steps:
      -
        name: Checkout
        uses: actions/checkout@v2
      -
        name: Docker meta
        id: meta
        uses: docker/metadata-action@v3
        with:
          # list of Docker images to use as base name for tags
          images: |
            DOCKERHUB_USERNAME/DOCKERHUB_IMAGENAME
          # generate Docker tags based on the following events/attributes
          tags: |
            type=schedule
            type=ref,event=branch
            type=ref,event=pr
            type=semver,pattern={{version}}
            type=semver,pattern={{major}}.{{minor}}
            type=semver,pattern={{major}}
            type=sha
      -
        name: Set up QEMU
        uses: docker/setup-qemu-action@v1
      -
        name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v1
      -
        name: Login to DockerHub
        if: github.event_name != 'pull_request'
        uses: docker/login-action@v1 
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}
      -
        name: Build and push
        uses: docker/build-push-action@v2
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

Create a Dockerfile

For example, if you have a static website or PHP application you could create a Dockerfile in the root of your repository like this:

FROM php:7.4-apache
COPY . /var/www/html

For node based applications a variation of this pattern could be useful:

FROM node:alpine
WORKDIR /app
COPY package.json ./
COPY package-lock.json ./
COPY ./ ./
RUN npm i
CMD ["npm", "run", "start"]

Tag and Push to GitHub

After you commit your code, tag the current version like this:

git tag v1.2.3

Then push the code to github, for example:

git push origin --tags

Github will then run actions automatically to deploy (or show you errors)

If you see an error like this:

Edit the file .github/workflows/ci.yaml, and replace the values of "DOCKERHUB_USERNAME" and "DOCKERHUB_IMAGENAME"

Locate image in Docker Hub

You can verify the image appears in DockerHub by logging in and checking your profile

And you can also verify the tags that are automatically pushed to Docker Hub

The docker image tag, which is based on your git repository tag is useful for specifying the active image that should be used in StackOS.

Note: Do NOT use latest as the "latest" tag will only be downloaded once. Specify the version label such as "0.0.2". It will be a little more work, but this practice will also save you when you need to quickly roll back to a known version.

If you have not yet funded your account you can do so at this point to reserve resources to deploy your pods

Account Funding - General

If you are launching your pod for the first time, here's a quick guide

Pod Launch - General